# Common HTTP based protocols best practises proposal

### Methods naming
`/api/<section.section>/<version>/<method.method>`

`section.section` - раздел API, потенциально отдельный подсервис
`version` - версия API конкретного подсервиса
`method.method` - название метода

*Alternatives*
`/api/<section.section(.version)/<method.method>`

#### Examples
`/api/gateway.firmwares/v1/upload.firmware`
`/api/auth/v1/login`
`/api/devices/v2/list`
`/api/devices/v2/patch`

*Alternatives*
`/api/gateway.firmwares/upload.firmware`
`/api/auth/login`
`/api/devices.v2/list`
`/api/devices.v2/patch`

### Result codes
* `200` - Successful request (prob with JSON ok inside as well)
* `302` - Redirect
* `404` - no method found
* `400` - Requester's error(with description in JSON)
* `401` - No Authentication provided (no description)
* `403` - Authentication error (no description)
* `405` - By RFC
* `429` - Rate limiting
* `451` - ??

### HTTP methods
#### `POST`
* all methods
* only JSON supported
* NO forms

#### `GET`
* only for safe and idempotent methods
* only some methods with small query

### Pagination:
`cursor` - last 'id' of element received
`limit` - length of list

### Connection
* Keep-Alive
* HTTP 2.0
* Headers compression

### Authentication:
* `Authentication: Bearer <token>`
* `Cookie` для UI
* Формат `token` или `cookie` - `<type>.<version>.<random string>`

### Security settings

#### CORS:
* Strict origin lists
* `localhost` allowed for DEV and Review envs

#### CSRF:
* SameSite for cookies
* Check origin and referers
* Strict CORS Origin
* Referer polict same-origin
*

## Notes
JSON protobuf mapping from Googgle
https://developers.google.com/protocol-buffers/docs/proto3#json

Handling WebHooks errors
https://api.slack.com/changelog/2016-05-17-changes-to-errors-for-incoming-webhooks

Versioning from Googgle
https://developers.google.com/blogger

Methods naming from Slack
https://api.slack.com/methods/chat.postMessage
https://api.slack.com/methods/team.billableInfo

Interesting event from Slack
https://api.slack.com/events/goodbye
https://api.slack.com/events/hello

CSRF Protection using CORS
https://owasp.org/www-community/attacks/csrf#related-controls
https://www.mixmax.com/engineering/modern-csrf