1This file describes steps and files needed when adding a new API to Chrome. 2Before you start coding your new API, though, make sure you follow the process 3described at: 4 http://www.chromium.org/developers/design-documents/extensions/proposed-changes/apis-under-development 5 6Two approaches are available for writing your API specification. The original 7approach relies on JSON specification files. The more recent and simpler system 8uses Web IDL files, but does not yet support all the features of the JSON files. 9Discuss with a member of the extensions team (aa@chromium.org) before you decide 10which approach is better suited to your API. 11 12The following steps suppose you're writing an experimental API called "Foo". 13 14-------------------------------------------------------------------------------- 15APPROACH 1: JSON FILES 16 171) Write your API specification. 18Create "chrome/common/extensions/api/experimental_foo.json". For inspiration 19look at the "app" API. Include descriptions fields to generate the 20documentation. 21 222) Add your API specification to api.gyp. 23Add "experimental_foo.json" to the "schema_files" section in 24"chrome/common/extensions/api/api.gyp". 25 263) Write the API function handlers. 27Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 28should use the JSON Schema Compiler. Look at the "permissions_api.cc" for 29details on how to do that. 30 31-------------------------------------------------------------------------------- 32APPROACH 2: IDL FILES 33 341) Write your API specification. 35Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look 36at "alarms.idl". Include comments, they will be used to automatically generate 37the documentation. 38 392) Add your API specification to api.gyp. 40Add "experimental_foo.idl" to the "schema_files" section in 41"chrome/common/extensions/api/api.gyp". 42 433) Write the API function handlers. 44Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 45should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on 46how to do that. 47 48-------------------------------------------------------------------------------- 49STEPS COMMON TO BOTH APPROACHES 50 516) Write support classes for your API 52If your API needs any support classes add them to 53"chrome/browser/extensions/api/foo". Some old APIs added their support classes 54directly to chrome/browser/extensions. Don't do that. 55 567) Update the project with your new files. 57The files you created in (3) and (5) should be added to 58"chrome/chrome_browser_extensions.gypi". 59 60-------------------------------------------------------------------------------- 61GENERATING DOCUMENTATION 62 638) Add a stub template in ../docs/templates/public corresponding to your API. 64See other templates for inspiration. 65 669) Run ../docs/templates/server2/preview.py to view the generated documentation. 67 68-------------------------------------------------------------------------------- 69WRITING TESTS 70 7112) Write a unit test for your API. 72Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of 73your API methods. See "alarms_api_unittest.cc" for details. Once done add your 74.cc to "chrome/chrome_tests.gypi". 75