design modern api - the right way
TRANSCRIPT
Projektowanie nowoczesnego API
jak zrobić to dobrze…
AgendaPodstawowe decyzje architektoniczne
Trochę więcej o architekturze
Wersjonowanie
Bezpieczeństwo
Żądania i odpowiedzi Resource’y i ich reprezentacje
Komunikaty o błędach
Podsumowanie
RESTArchitektura
Media Type
JSON
Protokół
HTTPS
Nie jestem RESTafarianinem ;)
REST PRINCIPLES Stateless
Cacheable
Client/Server
Uniform Interface
Resource-based
Resource manipulation through representation
Self-descriptive messages
HATEOAS
Layered System
Code on demand*
WersjonowanieURLhttps://api.example.com/v1Accept HeaderAccept: application/vnd.example.v1+jsonCustom Headerapi-version:1
Security
oAuth1.0a - bezpieczeństwo
oAuth2.0 - wygoda
HttpBasic - prostota
Własne - ?
Nagłówki i StatusyAccept: application/json; charset=utf-8Accept-encoding: gzipIf-none-match: jkshfsidniuds87h
Content-type: application/json; charset=utf-8Content-encoding: gzip
HTTP Verbs:post, put, get, delete
HTTP Status:2xx, 3xx, 4xx, 5xx
Nagłówki i Statusy200 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
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
Reprezentacja{ “href”: “http://api.example.com/v1/users/f7js9hj4”, “id”: “f7js9hj4”, “name”: “Jan Kowalski”, “email”: “[email protected]”, “friends”: { “href”: “http://api.example.com/v1/users/f7js9hj4/fiends” }, “createdAt”: “2014-01-28T14:38:30Z”}
Reprezentacja{ “href”: “http://api.example.com/v1/users?q[email][email protected]&page=4&perPage=10&order=createdAt,desc”, “next”: “http://api.example.com/v1/users?q[email][email protected]&page=5&perPage=10&order=createdAt,desc”, “prev”: “http://api.example.com/v1/users?q[email][email protected]&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”: “[email protected]”, “friends”: { “href”: “http://api.example.com/v1/users/f7js9hj4/fiends” }, “createdAt”: “2014-01-28T14:38:30Z” }, ] }
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"] },
PodsumowaniePamię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!
