Skip to main content

Rest API

Documentation OpenAPI​

Документація OpenAPI

Naming convintion​

!!! Example

``` js
// crud
HTTP GET http://api.example.com/api/managed-devices  //Get all devices
HTTP POST http://api.example.com/api/managed-devices  //Create new Device

HTTP GET http://api.example.com/api/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/api/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/api/managed-devices/{id}  //Delete device for given Id

// query param
HTTP GET http://api.example.com/api/managed-devices?region=USA
HTTP GET http://api.example.com/api/managed-devices?region=USA&ord=cdate
```

Status code​

Code

Додатково

Auth​

  • No auth - публічний доступ до API бе
  • API key - видається ключ який передається або в query &api_key=ApiKEY або Headers {Authorization:ApiKEY}
  • Bearer token - Headers {Authorization:Bearer Token} - токен може бути статичний або отриманий за допомогою OAuth,JWT
  • Basic auth - Headers {Authorization:base64(user pass)} - для авторизацій закритих nginx паролем
  • OAuth 2.0 - Стандарт визначає способи отримання токену, далі Bearer token

OAuth 2.0

👀 example "JWT"
// token
`${base64url(header)}.${base64url(payload)}.${signature}`

// api call
Authorization: Bearer {token}

app.post('/api/auth', (req, res) => {

    const user = getUser(req.query.user,req.query.pass);
    let head = Buffer.from(JSON.stringify({ alg:'HS256',typ:'jwt'})).toString('base64');
    let body = Buffer.from(JSON.stringify({uid:user.uid})).toString('base64');
    let signature = crypto.createHmac('SHA256',tokenKey).update(`${head}.${body}`)
    .digest('base64');

    return res.status(200).json({
        id: user.id,
        login: user.login,
        token: `${head}.${body}.${signature}`,
    })
})

:::example "OAUTH"

password

POST /oauth/token HTTP/1.1

grant_type=password&client_id=31337&client_secret=deadbeef&username=user&
password=qwerty

HTTP/1.1 200 OK
Content-Type: application/json

    {
    "access_token":"SlAV32hkKG",
    "token_type":"bearer",
    "expires_in":86400,
    "refresh_token":"8xLOxBtZp8",
    }

authorization_code (Auth Server)

    # Get Token
curl --request POST \
--url 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code","client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET","code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}'

# Call the API
curl --request GET \
--url https://api.atlassian.com/ex/jira/11223344-a1b2-3b33-c444-def123456789/rest/api/2/project \
--header 'Authorization: Bearer aBCxYz654123' \
--header 'Accept: application/json'

:::

Version​

import * as express from 'express';

// v1/get-ride.js
const router = express.Router();
router.post('/rides/:id', dep.verifyToken(), (req, res) => {
    // Your code
});
app.use('/api/v1', router);

// v2/get-ride.js
const router = express.Router();
router.post('/rides/:id', dep.verifyToken(), (req, res) => {
    // Your code
});
app.use('/api/v2', router);

GraphQL​

gRPC​

Не HTTP Протокол підходить для створення мікросервісів

HTTP 1.1 - 2 - 3​

Про роботу HTTP протоколу

Різниця між HTTP протоколоами v1.1,2,3