Skip to main content

Lesson 6. Requests and responses

Example 6.1. Request and response​

JSIGHT 0.3
 
POST /cats // Create a new cat.
  Request
    {
      "id"  : 123,
      "name": "Tom"
    }
 
  200
    "OK" // {const: true}
 
  404 any
  500 empty

This example describes the request POST /cats. The directive Request (line 4) specifies the requirements for the body of this request, whereas directives-responses 200, 404 and 500 specify how to react to this request (lines 10–14).

note

In this example, the so-called notations of the schema — any and empty (lines 14 and 15) are explicitly specified for responses 404 and 500. The notation of the schema defines which language is used to describe the schema in the body of the directive. The default notation is jsight, that is, the JSight Schema language, but sometimes it is more convenient to use other notations. This version of the language supports four notations: jsight, regex, any and empty.

info

For more information about this topic, see:

Example 6.2. Add headers​

JSIGHT 0.3
 
POST /cats // Create a new cat.
 
  Request
    Headers
      {
        "Content-Type": "application/json" // {const: true}
      }
    Body
      {
        "id"  : 123,
        "name": "Tom"
      }
 
  200
    Headers
      {
        "Content-Type": "application/json" // {const: true}
      }
    Body
      "OK" // {const: true}
 
  500 empty
  404 any

In this example, we have used the directive Headers to provide a description of the HTTP headers to the request POST /cats, as well as to a successful response 200 (lines 7–9 and 18–20).

The request or response body should always be defined under the directive Body when using the directive Headers (lines 10 and 21). If the directive Headers is missing, the directive Body can be omitted at the discretion of the documentation developer.

The directive Body has been omitted in the majority of the previous examples in this lesson.

note

The decision of possibly omitting the directive Body was taken since, in practice, the directive Headers is not used in the great majority of situations.

info

For more information about this topic, see: