User Tools

Site Tools


api_guidelines

[DRAFT] Proposed API Guidelines

Please review so and feedback can be incorporated before making official guidelines.

1 APIs

There are three types of APIs:

  1. Public
  2. Experimental
  3. Internal

1.1 Public APIs

Public APIs are the supported APIs that apps can use.

Public API requirements:

  • All public APIs must have at least one test case.
  • All public APIs must be in a header file that is published to the build directory.
  • All public APIs must be fully documented using doxygen markup in the public header files
  • All public APIs must be used in some sample code or snippet. Ideally, the sample should be one that is compiled as part of the build, and uses no experimental APIs. For rarely used public APIs, the sample might simply be a snippet in the doxygen comments.
  • Public APIs cannot have source- or binary- breaking changes across IoTivity versions. (Breaking changes can be made to a new API only until it is released for the first time.)

1.2 Experimental APIs

Experimental APIs are considered to be potential future public APIs, but there is no guarantee of support in future releases, nor is there any guarantee that breaking changes will not occur across releases.

Experimental API requirements:

  • Experimental APIs must be optional to compile in. That is, there must be some way to build IoTivity in a way that does not expose any experimental APIs, so that an application can easily verify that it uses only fully-supported public APIs, and so that the IoTivity code size requirement can be minimized.
  • Experimental APIs must be in a header file that is published to the build directory. They can be in their own header, or in a header file that is shared with public APIs but only if surrounded by an appropriate ifdef.
  • Experimental APIs should be fully documented using doxygen markup in the header file
  • Experimental APIs should ideally be used in some sample code (separate from samples that use only public APIs) or snippet. Ideally, the sample should be one that is compiled as part of the build. For rarely used APIs, the sample might simply be a snippet in the doxygen comments. Having working samples may help others evaluate and determine how ready it is for prime time before the API moves from experimental to public.

1.3 Internal APIs

Internal APIs are considered to be usable within IoTivity but are not intended to be used by applications that use IoTivity.

Internal API requirements:

  • Internal APIs must not appear in any header file that is published to the build directory
  • Internal APIs should ideally be documented using doxygen markup in the private header files
  • Internal APIs must not be used in sample code
  • Internal APIs must not be used by any apps other than test code. For example, this means that sample provisioning apps must not use internal APIs.

2 Programming Languages

There may be multiple programming languages supported (whether publically or experimentally). The API maintainer may have a separate sub-maintainer per programming language.

3 Breaking Changes

The API maintainer shall be responsible for API breaking change policy. The proposed policy is:

  • Public APIs cannot have source- or binary- breaking changes across releases, except as covered by deprecation as explained below. API additions can be made at any time.
  • Experimental and internal APIs can have breaking changes across releases.

APIs can be deprecated by marking them as @deprecated. The associated text should explain what an application should do instead. Public APIs must be @deprecated for at least two releases (i.e., one year of releases) before they can be removed. The reasons for deprecation of APIs should be discussed on the iotivity-dev list.

4 Gerrit review

All changes that affect any public API header must include the API function leader and/or appropriate language-specific experts as code reviewers. The language-specific experts are responsible for ensuring that the above guidelines are met, and also reviewing the doxygen documentation for completeness and clarity.

  • Java: Rick Bell
  • All others: Dave Thaler

Implementers are encouraged to discuss the proposed APIs on the iotivity-dev list before they are implemented, since changes are typically much more costly after the APIs are implemented.

api_guidelines.txt · Last modified: 2017/11/06 05:49 by Dave Thaler