JSON:API — работаем по спецификации

Граммар-наци

Граммар-наци

A SPECIFICATION FOR BUILDING APIS IN JSON

Junior

Интерфейс API

1. Создать статью
2. Получить список статей
3. Получить статью
4. Обновить статью
5. Удалить статью

Интерфейс

👌 Правильно

Удаляем статью

            DELETE /articles/1 HTTP/1.1
            Accept: application/json
        

            HTTP/1.1 200 OK
            Content-Type: application/json
            <ПУСТАЯ СТРОКА>
        

MIME-типы

• text/plain
• application/octet-stream
• application/pdf
• image/png
• application/json
• application/xml
• application/vnd.ms-excel

Коды ответов

Что можно было

• 201 Created
• 202 Accepted
• 204 No Content
• 403 Forbidden
• 404 Not Found
• 409 Conflict

Возвращайте ошибки

Создание сущности

            POST /articles HTTP/1.1
            Content-Type: application/json
            { "id": 1, "title": "Про JSON:API"}
        

            HTTP/1.1 422 Unprocessable Entity
            HTTP/1.1 403 Forbidden
            HTTP/1.1 500 Internal Server Error
        

👌 После

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/json
             
            { "errors": [{
                "status": "422",
                "title":  "Title already exist",
            }]}
        

Добавим паджинацию

Запрос списка

            GET /articles HTTP/1.1
            Content-Type: application/json
        

            HTTP/1.1 200 OK
            [
              { "id": 1, "title": "Про JSON:API"},
              { "id": 2, "title": "Про XML-RPC"}
            ]
        

👌 После

            GET /articles?page[size]=30&page[number]=2
            Content-Type: application/json
        

            HTTP/1.1 200 OK
            {
              "data": [{ "id": 1, "title": "JSON:API"}, ...],
              "meta": { "count": 10080 }
            }
        

👌 Или так

            GET /articles?page[offset]=30&page[limit]=30
            Content-Type: application/json
        

            HTTP/1.1 200 OK
            {
              "data": [{ "id": 1, "title": "JSON:API"}, ...],
              "meta": { "count": 10080 }
            }
        

👌 Или так

            GET /articles?page[published_at]=1538332156
            Content-Type: application/json
        

            HTTP/1.1 200 OK
            {
              "data": [{ "id": 1, "title": "JSON:API"}, ...],
              "meta": { "count": 10080 }
            }
        

Проблема N + 1

Выведем 10 статей с указанием автора

1. 1 запрос на получение статей
2. 10 запросов для получения авторов каждой статьи

Итого: 11 запросов

Добавляем связи

Запрос списка со связями

            GET /articles?include=author
            Content-Type: application/json
        

👌 Решение: запрос списка со связями

            HTTP/1.1 200 OK
            { "data": [{
              { attributes: { "id": 1, "title": "JSON:API" },
              { relationships: {
                "author": { "id": 1, "name": "Avdeev" } }
              }, ...
            }]}
        

👌 А ещё можно вот так

            GET /articles?include=author HTTP/1.1
        

            GET /articles?include=author,image HTTP/1.1
        

            GET /articles?include=author,author.avatar HTTP/1.1
        

Проблема дублирования данных

Выведем 10 статей с указанием автора, у всех статей один автор

Итого: один автор включен в ответ 10 раз

👌 Решение: нормализация данных

            HTTP/1.1 200 OK
            { "data": [{
                "id": "1", "type": "article",
                "attributes": { "title": "JSON:API" },
                "relationships": { ... }
              }, ... ]
            }
        

👌 Решение: нормализация данных

            HTTP/1.1 200 OK
            { "data": [{
                ...
                "relationships": {
                  "author": { "id": 1, "type": "people" } }
                }
              }, ... ]
            }
        

👌 Решение: нормализация данных

            HTTP/1.1 200 OK
            {
              "data": [ ... ],
              "included": [{
                "id": 1, "type": "people",
                "attributes": { "name": "Avdeev" }
              }]
            }
        

Нужны не все поля ресурса

👌 Решение

            GET /articles?fields[article]=title HTTP/1.1
        

            HTTP/1.1 200 OK
            { "data": [{
                "id": "1", "type": "article",
                "attributes": { "title": "Про JSON:API" },
              }, ... ]
            }
        

Поиск по статьям

👌 Решение

            GET /articles?filters[search]=api HTTP/1.1
        

            GET /articles?filters[from_date]=1538332156 HTTP/1.1
        

            GET /articles?filters[is_published]=true HTTP/1.1
        

            GET /articles?filters[author]=1 HTTP/1.1
        

Нужна сортировка

👌 Решение

            GET /articles?sort=title HTTP/1.1
        

            GET /articles?sort=published_at HTTP/1.1
        

            GET /articles?sort=-published_at HTTP/1.1
        

            GET /articles?sort=author,-published_at HTTP/1.1
        

Нужно поменять URLs

👌 Решение: гипермедиа (HATEOAS)

            GET /articles HTTP/1.1
            {
              "data": [{
                  ...
                  "links": { "self": "http://localhost/articles/1" },
                  "relationships": { ... }
              }],
              "links": { "self": "http://localhost/articles" }
            }
        

👌 Решение: гипермедиа (HATEOAS)

              ...
              "relationships": {
                "comments": {
                  "links": {
                    "self": "http://localhost/articles/1/relationships/comments",
                    "related": "http://localhost/articles/1/comments"
                  }
                }
              }
        

Новый Media Type

🌊 Экосистема JSON:API

Список реализаций спефикации — https://jsonapi.org/implementations/

1. ~190 различных реализаций
2. для ~30 языков программирования
3. и это только добавленные в каталог
4. PR welcome

➕ Плюсы JSON:API

1. Общее соглашение для всех
2. Меньше споров внутри команды
3. Высокая производительность разработки
4. Популярные проблемы уже решены
5. Прост для понимания
6. Лаконичен
7. Open Source

🤯 Минусы JSON:API

1. Фронтенд: надо парсить ответы
2. Бэкенд: контроль вложенности
3. Бэкенд: сложность запросов к БД
4. Бэкенд: безопасность
5. Спека сложно читается (не все смогли)
6. Не все либы реализуют спеку хорошо

Подводные камни JSON:API

🤔 Количество relationships в выдаче неограничено

            GET /articles/1?include=comments HTTP/1.1
        

              ...
              "relationships": {
                "comments": {
                  "data": [0 ... ∞]
                }
              }
        

☝️ Правильно

            GET /comments?filters[article]=1&page[size]=30 HTTP/1.1
        

            {
              "data": [0 ... 29]
            }
        

Неоднозначность

            GET /articles/1?include=comments HTTP/1.1
        

            GET /articles/1/comments HTTP/1.1
        

            GET /comments?filters[article]=1 HTTP/1.1
        

🤔 Полиморфные связи "один ко многим"

            GET /comments?include=commentable HTTP/1.1
             
              ...
              "relationships": {
                "commentable": {
                  "data": { "type": "article", "id": "1" }
                }
              }
        

🤔 Сложные связи "многие ко многим"

            GET /users?include=users_comments HTTP/1.1
             
              ...
              "relationships": {
                "users_comments": {
                  "data": [{ "type": "users_comments", "id": "1" }, ...]
                },
              }
        

OpenAPI (Swagger)

Чем JSON:API отличается
от GraphQL?

ВСЕМ

Альтернативы

OData (2015)

OData (2015) - the best way to REST

            GET http://services.odata.org/v4/TripRW/People HTTP/1.1
            OData-Version: 4.0
            OData-MaxVersion: 4.0
        

OData (2015) - the best way to REST

            HTTP/1.1 200 OK
            Content-Type: application/json; odata.metadata=minimal
            OData-Version: 4.0
            {
              '@odata.context': 'http://services.odata.org/V4/...
              '@odata.nextLink': 'http://services.odata.org/V4/...
              'value': [{
                '@odata.etag': 'W/'08D1D5BD423E5158'',
                'UserName': 'russellwhyte',
                ...
        

За подробностями

1. https://jsonapi.org
2. https://www.odata.org
3. https://graphql.org
4. http://xmlrpc.com/
5. https://www.jsonrpc.org

👏 Спасибо!

• 👨 Алексей Авдеев
• 🌐 https://github.com/avdeev
• 🌐 Neuron.Digital