Descriptions of the various Procore API endpoint release and end-of-life lifecycles.
API Endpoint Release Lifecycle
The Procore API Endpoint Release Lifecycle follows the workflow illustrated below.
The three stages in the lifecycle are described in the following table.
|Alpha||A version of the API that is actively developed against, not client facing, could change substantially without any notice (internally or externally)|
|Beta||A version of the API that is actively developed against, is client-facing as part of a beta program, may change semantically, and while all changes will be documented, they not be provided with advance notice.|
|Production||A version of the API that is actively in support mode, not actively developed against, is client facing and will not change substantially. Will be versioned and supported for some period of time.|
Use of Non-Production API Endpoints
Please note that Procore API endpoints which are not production-level are not subject to the lifecycle guidelines and policies described here. While endpoints may change semantically and all changes will be documented, advance notice of changes will not be provided in most cases. Therefore, we advise Procore Clients not to use non-production Procore API endpoints for their production integrations. Procore Technology Partners are not allowed to use non-production Procore API endpoints in their Marketplace applications as specified in the App Marketplace Software Requirements.
The Procore API Lifecycle is governed by the deprecation policies and timelines defined here. Procore API endpoints follow the end-of-life lifecycle as depicted below.
|Deprecated||A Generally Available (GA) API version is considered deprecated after Procore has publicly notified all users and clients of the timeline in which the API will no longer be supported (End of Support) and no longer be available (End of Life). Users are advised to upgrade to the current GA version. Deprecation for one version of an API endpoint will not occur unless a replacement version is GA.|
|End of Support||(Unsupported) Requests for Support will no longer be honored for an unsupported API version.|
|End of Life||(Unavailable) An Unavailable API version will no longer be accessible to public consumers. 404 Not Found errors will be returned against any endpoints that have reached End of Life.|
The following policies have been established for guiding the deprecation of Procore API endpoints.
- The API object that is subject to deprecation can be at any level of the API - either an entire version of API or individual endpoints.
- Only API endpoints at the
Productionsupport level are required to go through the deprecation process.
- A notification in the developer portal is created to announce deprecation. This message contains a detailed description of the API object subject to deprecation, a deprecation timeline that includes all stages and the duration of each stage, and an alternative option for similar functionality (assuming one exists).
- A new notification in the developer portal is created each time an API endpoint transitions to the next state in the End of Life Lifecycle.
The following timeline constraint is used to schedule deprecation events, activities, and announcements.
- There is a minimum 6 month time period between deprecation announcement and End of Support.
- End of Life can be coincident with End of Support.
For example, if the announcement is made that a given endpoint will be deprecated on November 1, 2016, then the earliest that endpoint could transition to the Unsupported stage would be May 1, 2017. Similarly, May 1, 2017 would be the earliest the endpoint could move to the Unavailable stage and it's functionality removed. It is important to note that this example illustrates the shortest possible timeline for moving an API endpoint through the End of Life Lifecycle using the 6 month minimum time period for deprecation.
Procore API Version Deprecation
Procore API v2.0 is currently the only supported version of the API at this time. As a result, Procore will continue to support deprecated v2.0 endpoints for 6 months from the time they were deprecated. Subsequent versions of the API will adhere to the Deprecation Timeline described above.