This section describes the versioning strategy used by the skeeled API.

A versioning policy is necessary in order to make backwards-incompatible (or "breaking") changes to the API while making sure client code is not susceptible to breakage because of those changes.

At skeeled, we use semantic versioning as standard to define versions and HTTP content negotiation to enable API endpoint level versioning.

Following the semantic versioning standard, we define which type of changes trigger a Major, Minor and Patch version change as follows:

Breaking changes (Major version change)

• Removing an endpoint
• Removing a required field or query property
• Changing a field or query property's type, default value, format or key (identifier)
• Changing the error message or status code for a specific scenario

Non breaking changes (Minor version change)

• Add a new endpoint or endpoint method
• Add a non required field or query property
• Add different error handling (error message or status code) for different scenarios

Note: Patch versions are usually changed when a backwards compatible bugfix is made

In summary, Major versions are only updated when changes that can break client code are made. Minor/patch versions are updated when a non breaking change is made.

In summary, HTTP content negotiation allows the client to specify which media type (or content type/format) it wants the server to handle the request/response content. It can be used to change the request/response body format (JSON, XML, etc) but it can also be used to request specific versions through custom media types values.

At skeeled, media types are used to version the data format used by the API. Internally, the version portion of the media type is matched against a known set of versions for that endpoint and the correct request/response body is expected/served.

NOTE: skeeled API only accepts/returns data in the standard format JSON.

Using custom media types, API clients can choose which version to use, they can protect their implementation from breaking when a new version is released and they can better manage API versions through deprecation/migration cycles.

All skeeled media types look like this:

application/vnd.skeeled[.version]+json

where the version part is optional

The most basic media types the API supports are:

application/json
application/vnd.skeeled+json

Neither of these specify a version, so you will always get the current default one.

Important: The default version of the API may change in the future. It is important that you specify a version if stability is important to you.

You can specify a version like so:

application/vnd.skeeled.v1.0.0+json
application/vnd.skeeled.v0.3.14+json

Since semantic versioning is used, you can specify a partial version identifier. For instance, if only the Major version is used (eg: application/vnd.skeeled.v1+json), the API will serve the latest version that matches the Major version 1, including the latest minor/patches.

You can check the used version through every response's headers. Look for the X-Skeeled-Media-Type header:

# Default version
$ curl https://app.skeeled.com/v2/version -I
> HTTP/1.1 200 OK
> X-Skeeled-Media-Type: application/vnd.skeeled.v1.0.0+json

# Version doesn't exist
$ curl https://app.skeeled.com/v2/version -I \
$  -H "Accept: application/vnd.skeeled.v0.0.100+json"
> HTTP/1.1 200 OK
> X-Skeeled-Media-Type: application/vnd.skeeled.v1.0.0+json

# Version exists
$ curl https://app.skeeled.com/v2/version -I \
$  -H "Accept: application/vnd.skeeled.v0.9.11+json"
> HTTP/1.1 200 OK
> X-Skeeled-Media-Type: application/vnd.skeeled.v0.9.11+json

As you can see from the examples, the following rules are applied:

1. If no version is requested, the current one (latest) is used
2. If an invalid/inexistent version is requested, the current one (latest) is used
3. If a valid version is requested, that version of the endpoint is used

At skeeled, old versions are maintained and continue available for a specific period of time. The current version of the API is the reference and older versions are marked as deprecated.

When any type of deprecation happens, clients will be contacted with details about what was deprecated, suggested changes and a timeline regarding when that version or endpoint will be completely removed from the API.

On the skeeled OpenAPI description, you can find deprecated endpoints or versions by looking for the deprecated: true key/value. It should exist in the operation level (endpoint definition) or content/schema level (content definition) as detailed below.

When a new version of the API is released, skeeled starts a cycle of communication with our clients (owner/admins) so that they can prepare and migrate to the new version as soon as possible:

1. Initial email communication detailing the changes made and which endpoints or endpoint versions were deprecated
2. A reminder after: 3 months, 6 months, 8 months, 8 months and 3 weeks (totaling 6 communications)
3. Deprecated API version is removed from the documentation
4. skeeled sends a final warning to clients that are still using the deprecated version
5. Deprecated version is removed from our API and is no longer available

Note: Only clients that currently use skeeled Public API will receive these communications

Endpoint deprecation can happen if:

• the endpoint is going to be removed
• the path or parameters of an existing endpoint are changed (renamed/removed)

This means that endpoint is marked to be removed completely from skeeled API and it's usage should be discontinued as soon as possible.

Policy

When a endpoint is marked as deprecated:

1. deprecated: true is added on the operation level in the OpenAPI description. Docs
2. The deprecation is communicated
3. At the end of the deprecation period, the endpoint is removed

OpenAPI example

'/example/{id}':
  get:
    summary: Operation example with multiple versions
    description: dummy
    operationId: exampleById
    deprecated: true
    tags:
      - test
    parameters:
      - name: id
        in: path
        required: true
        description: id
        schema:
          type: string
    responses:
      '200':
        description: Dummy response
        content:
          application/vnd.skeeled.v1.0.0+json:
            schema:
              $ref: '#/components/schemas/ExampleSchema'

Endpoint versions are deprecated when a new version is available for that endpoint. The same endpoint can be available in multiple versions at a given time as described here.

Policy

When a new version of an endpoint is made available, regarding the older version:

1. deprecated: true is added on the schema level in the OpenAPI description. Docs

• If the content block uses a $ref instead and the schema it points to is being used by other operations, the schema should be copied to its place and marked as deprecated there (see example)

2. The deprecation is communicated
3. At the end of the deprecation period, the endpoint version is removed

OpenAPI example

'/example/{id}':
  get:
    summary: Operation example with multiple versions
    description: dummy
    operationId: exampleById
    tags:
      - test
    parameters:
      - name: id
        in: path
        required: true
        description: id
        schema:
          type: string
    responses:
      '200':
        description: Dummy response
        content:
          application/vnd.skeeled.v1.0.0+json:
            schema:
              $ref: '#/components/schemas/ExampleSchema'
          application/vnd.skeeled.v0.3.14+json:
            schema:
              type: object
              deprecated: true
              properties:
                id:
                  type: integer
                  format: int64
                name:
                  type: string
              required:
                - id
                - name

Please refer here to find a complete changelog of our API: Download

Endpoints to access applicant data and perform application actions.

Endpoints to access offers

System Libraries endpoints

Endpoints to access users management