Child pages
  • API Versioning
Skip to end of metadata
Go to start of metadata

Why version the API?

  • Every time we release then we run the risk of breaking someone's client
  • By mandating API versioning then we can deploy multiple version alongside each other which we deprecate old versions of the API

Where do you put the version?

  • The version could be in the URL, in a custom header, or in the "Accept" header
  • Accept header versions the response, not the request
  • URL is user friendly, but departs from hypermedia as state
  • Custom header seems optimal
  • "X-ForgeRock-API-Version"

What does the version consist of?

  • CREST version X
  • Resource implementation version Y
  • Separated by semi-colon
  • "X;Y"

What are we versioning?

  • Number bumps when there is a non-backwards compatible change
  • Separate version for CREST (0 if CREST is not used), and the resource implementation

How to query which versions are present?

  • Check documentation (Swagger?)
  • Each request will return the specific version of the API that dealt with the request

How do we handle the version?

  • If the version in the header is deployed on the server then server the result as normal
  • If the version in the header is not deployed then provide an error message
  • If the version is not in the header then:
    • If mode is "allow" then just use the latest resource version available
    • If mode is "warn" then use the latest and provide a "_warning" attribute in the response
    • If mode is "deny" then provide an error message without handling



  1. Convert header to context
  2. Have the router deal with the version and provide error/warnings as necessary
  3. Ensure that the version can be expressed logically in CREST
  4. Matt to create JIRA issues for CREST
  5. Jonathan to remove version from authn URL, implement version header
  • No labels