API versioning and deprecation policy
Review information about the Boomi Enterprise Platform API objects' versioning and statuses, and 's current policy for deprecating API objects.
API Version status
An Boomi Enterprise Platform API object can have one of three statuses indicating its functional state.
-
Generally Available - A Generally Available API object is active and fully supported.
-
Deprecated - A deprecated API object is positioned for retirement at a future date. Though the object remains fully supported until its retirement date, Boomi recommends that users take advantage of newer API functionality meant to replace deprecated APIs at their earliest convenience. Operations for deprecated objects provide information in the response headers informing clients of the object’s status as well as deprecation and retirement dates.
-
Retired - A retired API object is no longer available for use. A feature retires after it is in a deprecated state for some time. Boomi recommends that users take advantage of newer API functionality to replace retired objects before their retirement date. Retired objects return a 410 error code if there is no replacement, or if available, return a 301 or 308 with a replacement URL pointing to the newer functionality.
Boomi communicates deprecation and retirement plans early and often to users. For deprecation time frames, refer to the topic Boomi feature deprecation process and policy.
Support level per status
Review the levels of account availability and support that are available for each status type.
| Generally Available | Deprecated | Retired | |
|---|---|---|---|
| Account availability | Active and available to all accounts. | Active and available for existing accounts only. New accounts do not have access. | Not available for all accounts. |
| Service-level agreement (SLA) and Support | Yes | Yes | No |
| Available for use in production | Yes | Yes | No |
| Documentation is supported and available | Yes | Yes | No |
Deprecation policy
Although works to make new updates to its APIs both non-breaking and backwards compatible, there are times when an API becomes outdated and we must deprecate the API to provide improved functionality to its users. guarantees full support for deprecated APIs until their retirement date. However, encourages users to use the new replacement API functionality as soon as possible.
Users and clients receive deprecation and retirement announcements through a variety of communication channels including but not limited to:
- Monthly release notes
- API documentation
- Direct emails
- Developer blogs
- API responses
Visit the deprecated object's documentation to identify newer object functionality to use in its stead.
For more information about 's deprecation policy, refer to the topic Boomi feature deprecation process and policy.
API versioning
does not use incremental versioning to indicate updates made to existing Boomi Enterprise Platform API objects. When updating existing Boomi Enterprise Platform API objects, ensures backward compatibility for clients and does not:
- Rename, remove, or change data types for existing fields
- Change field validation rules such as adding new, required fields
- Modify expected response codes
Boomi can modify existing API objects to add new, optional fields without advance notice. In some cases, might make changes to the logic implementation of a deprecated API to work with newer application features, however the API interface remains the same for clients. documents all changes made to Generally Available and deprecated APIs publicly, and communicates with you in release notes.
Example API response
The following example shows the return HTTP response header upon accessing the deprecated endpoint for the Atom Extensions object. Notice that the response returns headers with the object's original deprecation date, a warning message detailing the object's deprecated status, the link to the object's current documentation, and the object's future retirement (sunset) date of Saturday, February 13, 2021.
Deprecation: version ="1.0"; date="Sat, 12 Oct 2019 04:00:00 GMT"
Warning: 299 - "You are using a deprecated API endpoint. It will remain available until Sat, 13 Feb 2021 05:00:00 GMT. For more information see https://help.boomi.com/bundle/integration/page/r-atm-Atom_Extensions_object_62413e08-5155-44e9-95d4-fa2079b92538.html ."
Link: <https://help.boomi.com/bundle/integration/page/r-atm-Atom_Extensions_object_62413e08-5155-44e9-95d4-fa2079b92538.html;> rel="deprecation" type="text/html"
Sunset: Sat, 13 Feb 2021 05:00:00 GMT
When retiring an endpoint and no newer API functionality replaces the object, the retired object returns a 410 error code in the response. When retiring an endpoint and new API functionality is available, the retired object returns a 301 or 308 error code and a link to Documentation detailing the replacement object.
