Guidelines: Web Services (WS) and Application Programming Interfaces (APIs)

These guidelines do not apply to web services and APIs created prior to the release of these guidelines.  All future major version number releases of web services / APIs created prior to the establishment of these guidelines should adhere to these guidelines.   These guidelines do not apply to information systems used solely within an agency; however, agencies are encouraged to adopt these guidelines regarding their internal systems.

General Guidelines

1. All APIs should use any applicable statewide data standards and data definitions that exist at the time the API or version of the API is developed/implemented.
2. All REST APIs using JSON should conform to JSON API specification v1.0 at a minimum.
3. All REST APIs using XML should use Domain XML Standards.
4. All SOAP APIs should conform to W3C SOAP standard 1.2 at a minimum.
5. All SOAP APIs should conform to OASIS WS Security standard 1.1 at a minimum.
6. All SOAP APIs should conform to OASIS WS Federation standard 1.2 at a minimum.
7. All SOAP APIs should conform to OASIS WS Trust standard 1.4 at a minimum.
8. All Graph QL APIs should conform to the current GraphQL design specification available at http://GraphQL.org.
9. All APIs should use transport layer security (TLS) specification RFC 1.3 at a minimum.

10.All APIs should support availability and status notifications.

Documentation

11. APIs including all versions of an API should be documented prior to publication (moved from development to production).
12. All API documentation should be exposed in an API description language that is both human and machine readable .
13. All REST APIs should be documented in accordance with Open API  specification version 2.0 at a minimum.
14. All SOAP APIs should be documented in accordance with WSDL specification 1.1 (W3C note 15) at a minimum.

Versioning

15. All APIs should be versioned in accordance with Semantic Versioning 2.0.0 at a minimum.
16. A version number is mandatory for all published APIs; however, only the major version number should be exposed to clients.
17. API versions should be exposed via a header and/or as part of the URL.

Deprecation

• API deprecation should only apply to major version releases.
• An API should only be deprecated after a new major version release.
• All APIs should have a published deprecation notice and should be deprecated for at least 6 months before retirement unless otherwise specified by a service level agreement, legal/regulatory mandate, and/or new security requirement.
• Deprecation of an API should include an announcement and/or notification delivered to known consumers and be communicated within the API itself.
• Deprecation notifications should include the timeline for deprecation, how long the API will be supported post deprecation, and a link to the newest supported version of the API.