REST API

REpresentational State Transfer

Кожен запит від клієнта повинен містити всю інформацію, необхідну серверу для виконання запиту. Іншими словами, сервер не зобов'язаний зберігати інформацію про стан клієнта (ніяких сесій)

ПЛЮСИ

  • надійність (не потрібно зберігати стан клієнта, який можна втратити)

  • простіше масштабування (сесії, лоад балансер)

  • стандартизований інтерфейс (запити, відповіді, помилки)

  • по URL запиту легко зрозуміти які дані запитуються

Колекції / елементи

  • api.domain.ua/customers

  • api.domain.ua/customers/345

  • api.domain.ua/invoices

  • api.domain.ua/customers/345/subscriptons/

ДІЇ

  • GET /customers - отримати список клієнтів

  • POST /customers - створити нового

  • PUT /customers - оновити дані

  • DELETE /customers - видалити всіх

  • GET /customers/711 - отримати інформацію про клієнта

  • POST /customers/711

  • PUT /customers/711 - оновити інформацію клієнта

  • DELETE /customers/711 - видалити клієнта

ДІЇ

  • GET - лише отримання даних, дані не змінюються

  • POST/PUT/DELETE - зміна даних

  • GET/PUT/DELETE - багаторазовий виклик не повинен мати ефекту!

  • POST

HTTP status codes

  • 200 – OK

  • 400 – Bad Request

  • 401 – Unauthorized - користувач не авторизований

  • 403 – Forbidden - користувач не має прав доступу

  • 404 – Not found

  • ...

Best practices

Використовувати в назві імена, не дії

  • /subscriptions

  • /subscribe

  • /getInfoAboutAllCars

фільтрація/пейджинг/сортування/...

  • GET /cars?color=red

  • GET /cars?seats<=2

  • GET /cars?sort=-manufactorer,+model

  • GET /cars?fields=manufacturer,model,id,color

  • GET /cars?offset=10&limit=5

Вкладені або повязані колекції

  • /users/123/tasks

  • /customer/foxtrot/invoices

Можливість вернути одночасно дані, звязаної колекції

GET /tasks/123?expand=owner

{
    id: tsk_1234567890,
    title: 'Buy a milk',
    owner: {
        id: 'usr_1234567890',
        name: 'John',
        email: 'john@vakoms.com.ua'
    }
}

Версіонування

  • /v1.2/cars/

  • /2015-07-24/cars/

  • /cars?version=1.2

  • /cars/ + custom header: API-Version: 1.2

  • /cars/ + accept header: application/vnd.api.v2+json

Формат відповіді від сервера

  • Content-type: application/json

  • Content-type: application/xml

  • /cars.json

  • /cars?format=xml

Локалізація

  • Клієнт робить запит і очікує дані в певній локалізації

    Accept-Language: uk-UA

  • Сервер віддає дані і вказує локалізацію

    Content-Language: uk-UA

Формат відповідь

Header: 
    Content-type: application/json
    ...    
Status code: 200

Body:

{
  "data": 
   {
        "id": "usr_1234567890",
        "name": "John",
        "email": "john@vakoms.com.ua",
        "role": "author"
        ...
   },
   "links" : {
        ...
   }
}

Помилки (клієнта чи сервера)

Header: 
    Content-type: application/json
    ...    
Status code: 400

Body:

{
  "error": 
   {
        "message": "No car found in the database",
        "developerMessage": "Еhe requested resource does not exist",
        "type": "account-error"
        "code": 34,
        "moreInfo": "http://dev.domain.com/api/v1/errors/34"
   }
}

Використовуйте кастомні ІД для елементів ваших колекцій

  • job_d1a62016cba4ee83

  • usr_2d9b85fad42f64f8

  • adr_575a1b720bcdd6dc

Використовуйте кастомні ІД для елементів ваших колекцій

  • /users/usr_12345/jobs/job_12345

  • /customers/cus_2d9b85fad42f64f8

ІД для кожного запиту

можливо лише для важливих даних

Response Header: Request-id: req_123445678

Синхронні операції

Запит

POST /users/usr_12345/subscriptions

{
    "plan": "monthly",
    "trial": false
}

Синхронні операції

Відповідь

Headers:

  • Status: 201 Created

  • Location: /tasks/tsk_12345

Асинхронні операції

Запит:

POST /videos

{
    "source": "https://aws.domain.com/home-video-ep-99.mp4",
    "codec": "FFmpeg",
    "type": "encode-video"
}

Відповідь:

Headers:

  • Status: 202 Accepted

  • Location: /queue/32233

Асинхронні операції

Запит:

GET /queue/32233

Відповідь:

Headers:

  • Status: 200
{
    "status": "pending",
    "eta": "1234567890"
}

Асинхронні операції

Запит:

GET /queue/32233

Відповідь:

Headers:

  • Status: 303 See Other

  • Location: /videos/vid_12345

Асинхронні операції

Запит:

DELETE /queue/32233 - відміняємо дію

Rate limit

На кожен запит сервер повертає заголовки:

Headers:

  • Rate-Limit: макс. к-ть запитів в первний час (хвилину)
  • Rate-Remaining: скільки запитів ще залишилось до блокування
  • Rate-Reset: скільки секунд залишилось до оновлення ліміту

Якщо ваша програма перевищить ліміт запитів, сервер має вернути

Headers:

  • Status code: 429
  • Retry-After: 1000 к-ть секунд через яку можна повторити запит

Авторизація

Авторизація

  • Basic Auth в хеадерах шлем логін/пароль на кожен запит

  • Auth by token JWT

  • OAuth 2 окремий сервіс авторизації

Для чого документувати?

Як документувати

Apiary.io

Apiary.io online editor

Swagger.io

Swagger.io online editor

apidocjs.com

apidocjs.com

Aglio

Aglio

Aglio

Aglio

Slate

Slate

Slate

Changelog

Changelog