Backwards Compatibility

All resources and representations are maintained in a backwards compatible manner (please see the section below for what are considered backward compatible changes).

If any url or schema is updated in a future version, support for all pre-existent operations and schemas is preserved to ensure backwards compatibility.

This means that if a program is written against a version of our API, you can expect it will continue to work against future versions if implemented with the considerations detailed below.

Evolving scorecard issue types and factors

A very important exception to endpoint stability is that given our continuously evolving set of scorecard issue types and factors, endpoints specific to each of them might change as new type of security signals are added (or retired) from SecurityScorecard, or the specific attributes associated to their findings evolve.

In order to ensure integrations are prepared for this, it's important you use the endpoints available to determine the get metadata for all issue types that can be detec, or simply navigate to specific issue types using link urls in parent responses, eg. see `detail_url` for scorecard issues Get a company factor scores and issue counts, avoiding for example relying on a fixed list of issue types.

What is considered a non-breaking or backward compatible change?

All our API operations and schemas are kept backward compatible to ensure:

all existing requests working against the current version will continue to work in the future
all the responses continue to include the same information included currently, but can include additional new properties anywhere in the json response, that should be ignored or omitted on deserialization.

With this criteria, these are considered non-breaking or backward compatible changes:

new endpoints
new optional parameters:
- query parameters
- new optional properties in any part of a json request body
- new optional request http headers
new supported values of these request parameters
new properties in any part of a json response body
new response http headers
- this can include a pagination `Link` header, added to collections that after reaching a very large size we might need to introduce a fixed page size, see Pagination section.
- changes to the length or format of entity IDs or other opaque strings.
- issue types or factors being added, retired (if deemed obsolete as security signals), or changes to their associated severity and details
new event types in event logs (your code should ignore or gracefully handle unfamiliar event types)

And these would be considered breaking changes:

retiring existing endpoints
new required parameters
retiring support for values of these request parameters
retiring properties in any part of a json response body
modifying the type or meaning of existing properties
retiring response http headers
changes to expected http status codes

Additional properties in json responses

In most tech stacks this a non-issue and already contemplated in json libraries, but here are some references to special cases:

In java, when using jackson serializer set `FAIL_ON_UNKNOWN_PROPERTIES` to `false`, an example from swagger's official API client generator is shown here

Breaking Changes

While we're committed to keep all existing endpoints backward compatible it is possible a specific feature or functionality is retired from our product, whenever this happens:

we'll notify customers with a notice of 3 months minimum
we'll publish the event in this section
we'll provide assistance detailing a migration path if one is available