Versions Compared

Old Version 1

changes.mady.by.user Michael Peters

Saved on

compared with

New Version 2

changes.mady.by.user Michael Peters

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

CGRCAPI Specification

Introduction

The CGRCAPI Specification (CS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An CGRCAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Definitions

CGRCAPI Document
A document (or set of documents) that defines or describes an API. An CGRCAPI definition uses and conforms to the CGRCAPI Specification.

Path Templating
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.

Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item's Operations.

Media Types
Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with RFC6838.

Some examples of possible media type definitions:

text/plain; charset=utf-8
application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.text+json
application/vnd.github.v3.html+json
application/vnd.github.v3.full+json
application/vnd.github.v3.diff
application/vnd.github.v3.patch

HTTP Status Codes
The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by RFC7231 and registered status codes are listed in the IANA Status Code Registry.

Specification
Versions
The CGRCAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.

The major.minor portion of the semver (for example 3.0) SHALL designate the CS feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports CS 3.0 SHOULD be compatible with all CS 3.0.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.0.0 and 3.0.1 for example.

Each new minor version of the CGRCAPI Specification SHALL allow any CGRCAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the CGRCAPI property to the new minor version.

For example, a valid CGRCAPI 3.0.2 document, upon changing its CGRCAPI property to 3.1.0, SHALL be a valid CGRCAPI 3.1.0 document, semantically equivalent to the original CGRCAPI 3.0.2 document. New minor versions of the CGRCAPI Specification MUST be written to ensure this form of backward compatibility.

An CGRCAPI document compatible with CS 3.. contains a required CGRCAPI field which designates the semantic version of the CS that it uses. (CS 2.0 documents contain a top-level version field named swagger and value "2.0".)

Format
An CGRCAPI document that conforms to the CGRCAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

For example, if a field has an array value, the JSON array representation will be used:

{
"field": [ 1, 2, 3 ]
}
All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.

Patterned fields MUST have unique names within the containing object.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

Tags MUST be limited to those allowed by the JSON Schema ruleset.
Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by CGRCAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

Document Structure
An CGRCAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.

It is RECOMMENDED that the root CGRCAPI document be named: CGRCAPI.json or CGRCAPI.yaml.

Data Types
Primitive data types in the CS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00.

Primitives have an optional modifier property: format. CS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

The formats defined by the CS are:

type format Comments
integer int32 signed 32 bits
integer int64 signed 64 bits (a.k.a long)
number float
number double
string
string byte base64 encoded characters
string binary any sequence of octets
boolean
string date As defined by full-date - RFC3339
string date-time As defined by date-time - RFC3339
string password A hint to UIs to obscure input.
Rich Text Formatting
Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where CGRCAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

Relative References in URLs
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Relative references are resolved using the URLs defined in the Server Object as a Base URI.

Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.

Schema
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

CGRCAPI Object
This is the root document object of the CGRCAPI document.

Fixed Fields
Field Name Type Description
CGRCAPI string REQUIRED. This string MUST be the semantic version number of the CGRCAPI Specification version that the CGRCAPI document uses. The CGRCAPI field SHOULD be used by tooling specifications and clients to interpret the CGRCAPI document. This is not related to the API info.version string.
info Info Object REQUIRED. Provides metadata about the API. The metadata MAY be used by tooling as required.
servers [Server Object] An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.
paths Paths Object REQUIRED. The available paths and operations for the API.
components Components Object An element to hold various schemas for the specification.
security [Security Requirement Object] A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.
tags [Tag Object] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
externalDocs External Documentation Object Additional external documentation.
This object MAY be extended with Specification Extensions.

Info Object
The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

Fixed Fields
Field Name Type Description
title string REQUIRED. The title of the API.
description string A short description of the API. CommonMark syntax MAY be used for rich text representation.
termsOfService string A URL to the Terms of Service for the API. MUST be in the format of a URL.
contact Contact Object The contact information for the exposed API.
license License Object The license information for the exposed API.
version string REQUIRED. The version of the CGRCAPI document (which is distinct from the CGRCAPI Specification version or the API implementation version).
This object MAY be extended with Specification Extensions.

...

Format

An CGRCAPI document that conforms to the CGRCAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

For example, if a field has an array value, the JSON array representation will be used:

{
"field": [ 1, 2, 3 ]
}

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.

Patterned fields MUST have unique names within the containing object.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

  • Tags MUST be limited to those allowed by the JSON Schema ruleset.

  • Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Note: While APIs may be defined by CGRCAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

Document Structure

An CGRCAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.

It is RECOMMENDED that the root CGRCAPI document be named: CGRCAPI.json or CGRCAPI.yaml.

Data Types

Primitive data types in the CS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00.

Primitives have an optional modifier property: format. CS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

The formats defined by the CS are:

type format Comments
integer int32 signed 32 bits
integer int64 signed 64 bits (a.k.a long)
number float
number double
string
string byte base64 encoded characters
string binary any sequence of octets
boolean
string date As defined by full-date - RFC3339
string date-time As defined by date-time - RFC3339
string password A hint to UIs to obscure input.

Rich Text Formatting

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where CGRCAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Relative references are resolved using the URLs defined in the Server Object as a Base URI.

Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.

Schema

In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

CGRCAPI Object

This is the root document object of the CGRCAPI document.

Fixed Fields

Field Name Type Description
CGRCAPI string REQUIRED. This string MUST be the semantic version number of the CGRCAPI Specification version that the CGRCAPI document uses. The CGRCAPI field SHOULD be used by tooling specifications and clients to interpret the CGRCAPI document. This is not related to the API info.version string.
info Info Object REQUIRED. Provides metadata about the API. The metadata MAY be used by tooling as required.
servers [Server Object] An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.
paths Paths Object REQUIRED. The available paths and operations for the API.
components Components Object An element to hold various schemas for the specification.
security [Security Requirement Object] A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.
tags [Tag Object] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
externalDocs External Documentation Object Additional external documentation.

This object MAY be extended with Specification Extensions.

Info Object

The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

Fixed Fields

Field Name Type Description

...

title string

...

REQUIRED. The title of the API.
description string A short description of the API. CommonMark syntax MAY be used for rich text representation.
termsOfService string A URL to the Terms of Service for the API. MUST be in the format of a URL.
contact Contact Object The contact information for the exposed API.
license License Object The license information for the exposed API.

...

version string REQUIRED. The

...

version of the CGRCAPI document (which is distinct from the CGRCAPI Specification version or the API implementation version).

This object MAY be extended with Specification Extensions.Contact

Info Object Example


{
"name"title": "Sample Pet Store App",
"description": "API SupportThis is a sample server for a pet store.",
"urltermsOfService": "http://www.example.com/supportterms/",
"emailcontact": {
"support@example.com"
}
name: name": "API Support",
"url": "http://www.example.com/support",
"email": "support@example.com"
},
License

Contact Object

License Contact information for the exposed API.

Fixed Fields


Field Name Type Description
name string

...

The

...

identifying name

...

of the contact person/organization.
url string

...

The URL pointing to the

...

contact information. MUST be in the format of a URL.
email string The email address of the contact person/organization. MUST be in the format of an email address.

This object MAY be extended with Specification Extensions.

License Contact Object Example

{
"name": "

...

API Support",
"url": "

...

http://www.

...

example.

...

com/support",
"email": "support@example.com"
}
name:

...

API Support
url:

...

http://www.

...

example.

...

com/support
email: support@example.com

License Object

License information for the exposed API.

Fixed Fields
Field Name Type Description
name string REQUIRED. The license name used for the API.
url string A URL to the license used for the API. MUST be in the format of a URL.
This object MAY be extended with Specification Extensions.

Fixed Fields

Field Name Type Description
url string REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the CGRCAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
description string An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
variables Map[string, Server Variable Object] A map between a variable name and its value. The value is used for substitution in the server's URL template.
This object MAY be extended with Specification Extensions.

Server Object Example
A single server would be described as:

{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
}
url: https://development.gigantic-server.com/v1
description: Development server

The following shows how multiple servers can be described, for example, at the CGRCAPI Object's servers:

...

{
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example gigantic-server.com"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]
}
servers:

  • url: https://{username}.gigantic-server.com:{port}/{basePath}
    description: The production API server
    variables:
    username:
    # note! no enum here means it is an open value
    default: demo
    description: this value is assigned by the service provider, in this example gigantic-server.com
    port:
    enum:
    - '8443'
    - '443'
    default: '8443'
    basePath:
    # open meaning there is the opportunity to use special base paths as assigned by the provider, default is v2
    default: v2
    Server Variable Object
    An object representing a Server Variable for server URL template substitution.

...