Desinging the APIs for an internal set of services

1. for
DESIGNING THE APIS
an internal set of services

2. albertoleal
albertonb@gmail.com

4. https://github.com/globocom

5. for
DESIGNING THE
an internal
APIS
set of services

6. what is an API ?

7. micro-services
environment

8. "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.

14. ad$
A

15. Evolving a service
search
accounts
video
images

16. No restriction

17. Maintainable
and
Stable

18. Replacement

19. test the services?
HOWTO
define services contract?
manage deployment?

20. How do we get started
with our
API?

21. API Modeling

22. API Modeling - Conceptual Model

23. purpose

24. audience

25. developer,developer, developer

26. Developer
as a
Customer
API
as a
Product

27. API Modeling - Ubiquitous Language

28. API Modeling

29. !
Do not reinvent
the wheel
HAL
JSON API
JSON Schema
…

30. what makes a great API?

31. is
flexible
and
simple to use

32. /cars?fields=name,model,year
/cars

33. uses
nouns
instead of
verbs

34. /collection/<resource><?filters>
/cars/123?fields=name,model,year

35. /cars
/cars?status=new
/cars/123
/getAllCars
/getAllNewCars
/getCar/123

36. uses
HTTP Verbs
to perform operations
on the elements

37. Resource
POST
(create)
GET
(read)
PUT
(replace)
PATCH
(update)
DELETE
(delete)
/cars new car list all cars
new car
or
error
error
delete all
cars
/cars/123 error show car 123
update car
or
error
modify car
or
error
delete car
123

38. returns meaningful errors

40. 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

41. 400 - 401 - 403 - 404 - 500
Bad Request Forbidden
Unauthorized Not Found
Internal Server Error

42. provides great support

43. Documentation

45. Documentation

46. Documentation Communication

47. CommunityDocumentation Communication

48. is secure

49. what about versioning?

50. application/vnd.example.com+json; version=1
application/vnd.example.com.v1+json;
Accept:

51. test the services?
HOWTO
define services contract?
manage deployment?

52. ad$
A

55. contracts enable
service independence

56. but…

57. "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.

58. Contracts can also
couple
service providers
and
consumers

62. {
"title": "App",
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"uris": {
"type": "array",
"title":"URIs",
"items": {
"type": "string"
}
}
},
"required": ["name"]
}
required fields

63. {
"links": [
{
"href": "https://domain/apps",
"method": "POST",
"rel": “create”,
"schema": {
"$ref": "https://domain/schemas/apps/new_app"
}
}
…
]
}

64. Consumer-Driven Contracts:
A Service Evolution Pattern
http://martinfowler.com/articles/consumerDrivenContracts.html

65. test the services?
HOWTO
define services contract?
manage deployment?

66. Deployment
imagessearch

67. Deployment
search

68. Deployment

69. test the services?
HOWTO
define services contract?
manage deployment?

71. Contract
Tests
Integration
Tests

72. be positive

73. thanks!
@albertoleal
albertonb@gmail.com