Create a diff

POST /diffs

Create a diff between any two given API definitions. The diff result will be available asynchronously and needs to be retrieved with the GET /diffs/:id API endpoint.

Body

The diff creation request object

  • url string(uri)

    Required if definition is not present. Current definition URL. It should be accessible through HTTP by Bump servers.

  • previous_url string(uri)

    Required if definition is not present. Previous definition URL. It should be accessible through HTTP by Bump servers.

  • previous_definition string

    Required if url is not present. Serialized definition of the previous version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file serialized as a string, in YAML or JSON.

  • previous_references array[object]

    Import external references used by previous_definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.

    Hide previous_references attributes Show previous_references attributes array[object]
    • location string

      Location of the external reference as it's called from definition, without the relative path (the part after #/). Can be an URL of a file system path.

    • content string

      Content of the external reference, as a string.

  • definition string

    Required if url is not present. Serialized definition of the current version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file serialized as a string, in YAML or JSON.

  • references array[object]

    Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.

    Hide references attributes Show references attributes array[object]
    • location string

      Location of the external reference as it's called from definition, without the relative path (the part after #/). Can be an URL of a file system path.

    • content string

      Content of the external reference, as a string.

  • expires_at string(date-time)

    Public change expiration date and time. After this date, this documentation change will be destroyed.

Responses

  • 201

    Diff successfully created

    Hide response attribute Show response attribute object
    • id string

      Unique id of your diff
  • 422

    Definition is not valid.

    Hide response attributes Show response attributes object
    • message string

      Human readable error message.

    • errors object

      Hash of invalid attributes with their error messages.
POST /diffs 
curl \
 -X POST https://bump.sh/api/v1/diffs \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com","previous_url":"https://example.com","previous_definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n","previous_references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"expires_at":"2022-02-22T22:20:22Z"}'
Request example 
{
  "url": "https://example.com",
  "previous_url": "https://example.com",
  "previous_definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "previous_references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "expires_at": "2022-02-22 22:20:22 UTC"
}
Request examples 
{
  "url": "https://example.com",
  "previous_url": "https://example.com",
  "previous_definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "previous_references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "expires_at": "2022-02-22T22:20:22Z"
}
Response examples (201) 
{
  "id": "d6f00a51-a175-4a44-a0c7-df62a48548ca"
}
Response examples (201) 
{
  "id": "d6f00a51-a175-4a44-a0c7-df62a48548ca"
}
Response examples (422) 
{
  "message": "Invalid definition file",
  "errors": {
    "raw_definition": [
      "The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
    ]
  }
}
Response examples (422) 
{
  "message": "Invalid definition file",
  "errors": {
    "raw_definition": [
      "The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
    ]
  }
}