designing the apis for an internal set of services
DESCRIPTION
Desinging the APIs for an internal set of servicesTRANSCRIPT
for
DESIGNING THE APIS
an internal set of services
https://github.com/globocom
forDESIGNING THE
an internal
APIS
set of services
what is an API ?
micro-services environment
"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.
ad$
A
Evolving a service
search
accounts
video
images
No restriction
Maintainable and
Stable
Replacement
test the services?
HO
W T
Odefine services contract?
manage deployment?
How do we get started with our
API?
API Modeling
API Modeling - Conceptual Model
purpose
audience
developer,developer, developer
Developer as a
Customer
API as a
Product
API Modeling - Ubiquitous Language
API Modeling
!Do not reinvent the wheel
HAL JSON API
JSON Schema
…
what makes a great API?
is
flexible and
simple to use
/cars?fields=name,model,year
/cars
uses
nouns instead of
verbs
/collection/<resource><?filters>
/cars/123?fields=name,model,year
/cars /cars?status=new /cars/123
/getAllCars /getAllNewCars /getCar/123
uses
HTTP Verbs to perform operations
on the elements
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
returns meaningful errors
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
400 - 401 - 403 - 404 - 500
Bad Request Forbidden
Unauthorized Not Found
Internal Server Error
provides great support
Documentation
Documentation
Documentation Communication
CommunityDocumentation Communication
is secure
what about versioning?
application/vnd.example.com+json; version=1
application/vnd.example.com.v1+json;
Accept:
test the services?
HO
W T
Odefine services contract?
manage deployment?
ad$
A
contracts enable
service independence
but…
"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.
Contracts can also
couple service providers
and
consumers
{ "title": "App", "type": "object", "properties": { "name": { "type": "string", "title": "Name" }, "uris": { "type": "array", "title":"URIs", "items": { "type": "string" } } }, "required": ["name"]}
required fields
{ "links": [ { "href": "https://domain/apps", "method": "POST", "rel": “create”, "schema": { "$ref": "https://domain/schemas/apps/new_app" } } … ]}
Consumer-Driven Contracts: A Service Evolution Pattern
http://martinfowler.com/articles/consumerDrivenContracts.html
test the services?
HO
W T
Odefine services contract?
manage deployment?
Deployment
imagessearch
Deployment
search
Deployment
test the services?
HO
W T
Odefine services contract?
manage deployment?
Contract Tests
IntegrationTests
be positive
