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 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.
The Hexlet support team or other students will answer you.
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.
Programming courses for beginners and experienced developers. Start training for free
Our graduates work in companies:
Sign up or sign in
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.