1. Projektowanie
nowoczesnego API
jak zrobić to dobrze…

2. Agenda
Podstawowe decyzje architektoniczne
Trochę więcej o architekturze
Wersjonowanie
Bezpieczeństwo
Żądania i odpowiedzi
Resource’y i ich reprezentacje
Komunikaty o błędach
Podsumowanie

3. REST
Architektura

5. Media Type
JSON

7. Protokół
HTTPS

8. Nie jestem
RESTafarianinem ;)

9. REST PRINCIPLES
Stateless
Cacheable
Client/Server
Uniform Interface
Resource-based
Resource manipulation through representation
Self-descriptive messages
HATEOAS
Layered System
Code on demand*

10. Wersjonowanie
URL
https://api.example.com/v1
Accept Header
Accept: application/vnd.example.v1+json
Custom Header
api-version:1

11. Security
oAuth1.0a - bezpieczeństwo
oAuth2.0 - wygoda
HttpBasic - prostota
Własne - ?

12. Nagłówki i Statusy
Accept: application/json; charset=utf-8
Accept-encoding: gzip
If-none-match: jkshfsidniuds87h
Content-type: application/json; charset=utf-8
Content-encoding: gzip
HTTP Verbs:
post,put, get,delete
HTTP Status:
2xx, 3xx,4xx,5xx

13. Nagłówki i Statusy
200 OK
201 Created
202 Accepted
204 No Content
304 Not Modified
400 Bad Request
401 Unauthorized (Unauthenticated)
403 Forbidden
404 Not Found
405 Method not Allowed
409 Conflict
429 Too Many Request

14. URL
/products
/products/1hd84hb
/cars/alfaromeo/166
/users/jf74jd/messages?type=closed&page=4&perPage=10
/users/jdf8734hd/friends?order=createdAt,desc&fields=email,name

15. Reprezentacja
{
“href”: “http://api.example.com/v1/users/f7js9hj4”,
“id”: “f7js9hj4”,
“name”: “Jan Kowalski”,
“email”: “jan@kowalski.pl”,
“friends”: {
“href”: “http://api.example.com/v1/users/f7js9hj4/fiends”
},
“createdAt”: “2014-01-28T14:38:30Z”
}

16. Reprezentacja
{
“href”: “http://api.example.com/v1/users?q[email]=@wp.pl&page=4&perPage=10&order=createdAt,desc”,
“next”: “http://api.example.com/v1/users?q[email]=@wp.pl&page=5&perPage=10&order=createdAt,desc”,
“prev”: “http://api.example.com/v1/users?q[email]=@wp.pl&page=4&perPage=10&order=createdAt,desc”,
“filters”:{
“email”: “@wp.pl”,
“page”: 4,
“perPage”: 10
“order”: createdAt,desc
},
“items”: [{
“id”: “f7js9hj4”,
“name”: “Jan Kowalski”,
“email”: “jan.kowalski@wp.pl”,
“friends”: {
“href”: “http://api.example.com/v1/users/f7js9hj4/fiends”
},
“createdAt”: “2014-01-28T14:38:30Z”
},
]
}

17. Błędy
{
“error”:”1”,
“message”:”An error occurs”
}
"2000": {
"httpCode": 400,
"internalCode": 2000,
"developerMessage": "Your request has incorrect format.",
"codeDescription": "Cannot understand this request, please check if all mandatory field are filled",
"moreInfo": "http://dev.example.com/erros/2000",
"context": ["Field email must have valid email address!", "You must specify campaignId"]
},

18. Podsumowanie
Pamiętaj że klientami twojego API są programiści,
Nie zaniedbuj czytelności API zwłaszcza w wypadku
błędów,
Wykorzystuj standardy,
Zachowuj kompatybilność wsteczną i zaplanuj długie
cykle życia wersji,
Planuj strukturę reprezentacji zasobów (enveloping),
Rozmawiaj ze swoimi klientami!

19. Dziękuję za uwagę
michal.giergielewicz@getresponse.com