Designing the APIs for an internal set of services
-
Upload
alberto-leal -
Category
Technology
-
view
97 -
download
1
description
Transcript of Designing the APIs for an internal set of services
![Page 1: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/1.jpg)
for
DESIGNING THE APIS
an internal set of services
![Page 3: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/3.jpg)
![Page 4: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/4.jpg)
https://github.com/globocom
![Page 5: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/5.jpg)
forDESIGNING THE
an internal
APIS
set of services
![Page 6: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/6.jpg)
what is an API ?
![Page 7: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/7.jpg)
micro-services environment
![Page 8: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/8.jpg)
"A concept where an application is
decomposed into small and loosely coupled
services, where each service has a single
responsibility, running in its own process.
![Page 9: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/9.jpg)
![Page 10: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/10.jpg)
![Page 11: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/11.jpg)
![Page 12: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/12.jpg)
![Page 13: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/13.jpg)
![Page 14: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/14.jpg)
ad$
A
![Page 15: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/15.jpg)
Evolving a service
search
accounts
video
images
![Page 16: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/16.jpg)
No restriction
![Page 17: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/17.jpg)
Maintainable and
Stable
![Page 18: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/18.jpg)
Replacement
![Page 19: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/19.jpg)
test the services?
HO
W T
Odefine services contract?
manage deployment?
![Page 20: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/20.jpg)
How do we get started with our
API?
![Page 21: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/21.jpg)
API Modeling
![Page 22: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/22.jpg)
API Modeling - Conceptual Model
![Page 23: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/23.jpg)
purpose
![Page 24: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/24.jpg)
audience
![Page 25: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/25.jpg)
developer,developer, developer
![Page 26: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/26.jpg)
Developer as a
Customer
API as a
Product
![Page 27: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/27.jpg)
API Modeling - Ubiquitous Language
![Page 28: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/28.jpg)
API Modeling
![Page 29: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/29.jpg)
!Do not reinvent the wheel
HAL JSON API
JSON Schema
…
![Page 30: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/30.jpg)
what makes a great API?
![Page 31: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/31.jpg)
is
flexible and
simple to use
![Page 32: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/32.jpg)
/cars?fields=name,model,year
/cars
![Page 33: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/33.jpg)
uses
nouns instead of
verbs
![Page 34: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/34.jpg)
/collection/<resource><?filters>
/cars/123?fields=name,model,year
![Page 35: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/35.jpg)
/cars /cars?status=new /cars/123
/getAllCars /getAllNewCars /getCar/123
![Page 36: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/36.jpg)
uses
HTTP Verbs to perform operations
on the elements
![Page 37: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/37.jpg)
ResourcePOST
(create)GET
(read)PUT
(replace)PATCH
(update)DELETE (delete)
/cars new car list all carsnew car
or error
errordelete all
cars
/cars/123 error show car 123update car
or error
modify car or
error
delete car 123
![Page 38: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/38.jpg)
returns meaningful errors
![Page 39: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/39.jpg)
![Page 40: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/40.jpg)
HTTP/1.1 400 Bad Request!!{ "errorCode" : 123, "moreInfo": “http://dev.api.com/errors/123" "errors": [ { "name": [ “can’t be blank" ] } ]}
use http status code
payload as verbose as possible
![Page 41: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/41.jpg)
400 - 401 - 403 - 404 - 500
Bad Request Forbidden
Unauthorized Not Found
Internal Server Error
![Page 42: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/42.jpg)
provides great support
![Page 43: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/43.jpg)
Documentation
![Page 44: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/44.jpg)
![Page 45: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/45.jpg)
Documentation
![Page 46: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/46.jpg)
Documentation Communication
![Page 47: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/47.jpg)
CommunityDocumentation Communication
![Page 48: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/48.jpg)
is secure
![Page 49: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/49.jpg)
what about versioning?
![Page 50: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/50.jpg)
application/vnd.example.com+json; version=1
application/vnd.example.com.v1+json;
Accept:
![Page 51: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/51.jpg)
test the services?
HO
W T
Odefine services contract?
manage deployment?
![Page 52: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/52.jpg)
ad$
A
![Page 53: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/53.jpg)
![Page 54: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/54.jpg)
![Page 55: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/55.jpg)
contracts enable
service independence
![Page 56: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/56.jpg)
but…
![Page 57: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/57.jpg)
"A concept where an application is
decomposed into small and loosely coupled services, where each service has a single
responsibility, running in its own process.
![Page 58: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/58.jpg)
Contracts can also
couple service providers
and
consumers
![Page 59: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/59.jpg)
![Page 60: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/60.jpg)
![Page 61: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/61.jpg)
![Page 62: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/62.jpg)
{ "title": "App", "type": "object", "properties": { "name": { "type": "string", "title": "Name" }, "uris": { "type": "array", "title":"URIs", "items": { "type": "string" } } }, "required": ["name"]}
required fields
![Page 63: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/63.jpg)
{ "links": [ { "href": "https://domain/apps", "method": "POST", "rel": “create”, "schema": { "$ref": "https://domain/schemas/apps/new_app" } } … ]}
![Page 64: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/64.jpg)
Consumer-Driven Contracts: A Service Evolution Pattern
http://martinfowler.com/articles/consumerDrivenContracts.html
![Page 65: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/65.jpg)
test the services?
HO
W T
Odefine services contract?
manage deployment?
![Page 66: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/66.jpg)
Deployment
imagessearch
![Page 67: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/67.jpg)
Deployment
search
![Page 68: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/68.jpg)
Deployment
![Page 69: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/69.jpg)
test the services?
HO
W T
Odefine services contract?
manage deployment?
![Page 70: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/70.jpg)
![Page 71: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/71.jpg)
Contract Tests
IntegrationTests
![Page 72: Designing the APIs for an internal set of services](https://reader034.fdocuments.us/reader034/viewer/2022052602/559b5ff51a28ab0a5f8b45c9/html5/thumbnails/72.jpg)
be positive