Designing the APIs for an internal set of services

for

DESIGNING THE APIS

an internal set of services

albertoleal

[email protected]

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

thanks!@albertoleal

[email protected]