HTTP Endpoints

HTTP Endpoints

Here's an example of HTTP endpoint definition:

http:                        #  HTTP Endpoints
  sample:                    #  API
    get_sample:              #  Endpoint
      endpoint: GET /sample
      response:
        ok: Sample

The http field of the spec is a dictionary where each item represents an API.

API

API is a logical grouping of endpoints. This grouping is important for code generation as it allows to split code into logically separate files/classes.

Each key in the http dictionary is a name of the API and value is a dictionary defining endpoints belonging to the API.

Here's an example of two APIs books and authors with two endpoints in each.

http:
  books:                       # Books API
    all_books:
      endpoint: GET /books
      response:
        ok: Books
    add_book:
      endpoint: POST /books
      body: Book
      response:
        ok: empty
  authors:                     # Authors API
    all_authors:
      endpoint: GET /authors
      response:
        ok: Authors
    add_author:
      endpoint: POST /authors
      body: Author
      response:
        ok: empty

Endpoint

Here's an example of endpoint definition:

create_sample:
  description: creates sample
  endpoint: POST /sample
  header:
    Authorization: string
  query:
    sample_id: uuid
    user_id: int?
  body: Sample
  response:
    ok: Sample
    forbidden: empty

Here's information about endpoint definition fields:

Field	Required	Details
description	no	description, used for documentation
endpoint	yes	HTTP method and endpoint URL
header	no	dictionary of HTTP header parameters and their types
query	no	dictionary of HTTP query parameters and their types
body	no for POST and PUT	HTTP body of the request
response	yes	dictionary of supported HTTP responses and response body

Endpoint Field

Endpoint defines HTTP method and URL to which service should respond.

Endpoint has the following format: METHOD url. Method might be one of follwing: GET, POST, PUT, DELETE.

Url is just a string always starting from /. Url can contain parameters in following format: {param:type}. Here's an example for enpoint with url parameter:

GET /sample/{id:uuid}

Parameters

This section describes parameters format that is used for both header parameters and query parameters.

parameter: type [= default_value] [# description]

	Required	Details
parameter	yes	parameter name
type	yes	type of parameter according to types
default_value	no	default value for the parameter
description	no	description in a form of line comment, used for documentation

Here's an example of parameter page_size of type int default value 20 and description number of items per page:

page_size: int = 20  # number of items per page

Here's an example of parameter page of type int without default value or description:

page: int

Header Parameters

The header field of endpoint allows to define HTTP header parameters. The header field value is a dictionary where each item is using parameters format.

Here's an example of two header parameters definition: Authorization (string) and X-Request-Id (uuid):

header:
  Authorization: string  # authorization token
  X-Request-Id: uuid     # original request id passed

Omit header field in endpoint defintion if there no header parameters needed.

Query Parameters

The query field of endpoint allows to define HTTP header parameters. The query field value is a dictionary where each item is using parameters format.

Here's an example of two query parameters definition: page_size (int) and page_number (int):

query:
  page_size: int = 100  # size of the page
  page_number: int      # number of requested page

Omit query field in endpoint defintion if there no query parameters needed.

Request Body

The body field of endpoint defines body type of HTTP endpoint request.

Here's an example of body definition represented by custom type Sample:

body: Sample  # sample that will be created

The body field can not have default value. Omit body field in endpoint definition if request body is not required.

Response

Here's an example of response definition with 2 responses: ok and forbidden, the ok response has a body of type Sample along with descriptions:

response:
  ok: Sample        # sample is created
  forbidden: empty  # user is forbidden to create sample

The response field of endpoint defines all possible responses of the HTTP endpointed. The response is a dictionary where key is the name of the response and value is the type of the response. Responses names should be in a text form according to RFC 7231 but in snake_case. So, OK will be ok, Unauthorized - unauthorized, Method Not Allowed - method_not_allowed, etc.

At least one response should be always defined for any HTTP endpoint.