Register to get access to free programming courses with interactive exercises

OpenAPI (used to be Swagger Specification) HTTP API

The REST style leaves a lot of decisions up to the developers. On the one hand, this is proper, the task of REST is not to set a specification, but to define the principles that allow you to build a good HTTP API. In this sense, REST is a very well-thought-out concept, doesn't depend on trends, and has existed for decades without change. On the other hand, the freedom in how links are organized, and what data structures are sent and returned, means all REST APIs are quite different and sometimes quite strong.

This leads to a large number of problems, which are easily solved in the RPC protocols:

  • The documentation is described manually and is different in each API.
  • There's no automatic verification to make sure the calls and parameters being passed are correct.
  • And the language doesn't generate test code or data structures to work with API data.
  • There's of static analysis, such as highlighting incorrect queries in the editor

The OpenAPI standard was developed to solve these and other issues. This is a simple and language-independent way to describe the API in a format that both machines and humans can understand. It's used to automatically generate documentation, tests, and code for executing queries and checking the correctness of data.

# OpenAPI descriptions are best written in yaml format
# Example using a pet store

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"

Here we can see a set of endpoints that define the structure of the parameters expected to be input and the output data. Using this description and the relevant libraries for each language, we can generate documentation, test code, the necessary classes to store this data, and even a library to perform queries to this API.


Recommended materials

  1. OpenAPI Specification

Hexlet Experts

Are there any more questions? Ask them in the Discussion section.

The Hexlet support team or other students will answer you.

About Hexlet learning process

For full access to the course you need a professional subscription.

A professional subscription will give you full access to all Hexlet courses, projects and lifetime access to the theory of lessons learned. You can cancel your subscription at any time.

Get access
130
courses
1000
exercises
2000+
hours of theory
3200
tests

Sign up

Programming courses for beginners and experienced developers. Start training for free

  • 130 courses, 2000+ hours of theory
  • 1000 practical tasks in a browser
  • 360 000 students
By sending this form, you agree to our Personal Policy and Service Conditions

Our graduates work in companies:

<span class="translation_missing" title="translation missing: en.web.courses.lessons.registration.bookmate">Bookmate</span>
<span class="translation_missing" title="translation missing: en.web.courses.lessons.registration.healthsamurai">Healthsamurai</span>
<span class="translation_missing" title="translation missing: en.web.courses.lessons.registration.dualboot">Dualboot</span>
<span class="translation_missing" title="translation missing: en.web.courses.lessons.registration.abbyy">Abbyy</span>
Suggested learning programs

From a novice to a developer. Get a job or your money back!

Frontend Developer icon
Profession
beginner
Development of front-end components for web applications
start anytime 10 months

Use Hexlet to the fullest extent!

  • Ask questions about the lesson
  • Test your knowledge in quizzes
  • Practice in your browser
  • Track your progress

Sign up or sign in

By sending this form, you agree to our Personal Policy and Service Conditions
Toto Image

Ask questions if you want to discuss a theory or an exercise. Hexlet Support Team and experienced community members can help find answers and solve a problem.