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
200 – OK
400 – Bad Request
401 – Unauthorized - користувач не авторизований
403 – Forbidden - користувач не має прав доступу
404 – Not found
...
/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": "pending",
"eta": "1234567890"
}
Запит:
GET /queue/32233
Відповідь:
Headers:
Status: 303 See Other
Location: /videos/vid_12345
Запит:
DELETE /queue/32233 - відміняємо дію
На кожен запит сервер повертає заголовки:
Headers:
Якщо ваша програма перевищить ліміт запитів, сервер має вернути
Headers:
Basic Auth в хеадерах шлем логін/пароль на кожен запит
Auth by token JWT
OAuth 2 окремий сервіс авторизації