RailsConf 2014 - Designing the APIs for an internal set of services

The success of an API is measured by how fast and easy developers can integrate with that.

In the micro-services environment, where each service has a well-defined responsibility, it's not enough to have a well designed API, it's necessary to establish a contract between the APIs, so the integration between them may be feasible.

Transcript

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.
9. ad$ A
10. Evolving a service search accounts video images
11. No restriction
12. Maintainable and Stable
13. Replacement
14. test the services? HOW TO define services contract? manage deployment?
15. How do we get started with our API?
16. API Modeling
17. API Modeling - Conceptual Model
18. purpose
19. audience
20. developer, developer, developer
21. Developer as a Customer API as a Product
22. API Modeling - Ubiquitous Language
23. API Modeling
24. !Do not reinvent the wheel HAL JSON API JSON Schema …
25. what makes a great API?
26. is flexible and simple to use
27. /cars?fields=name,model,year /cars
28. uses nouns instead of verbs
29. /collection/<resource><?filters> /cars/123?fields=name,model,year
30. /cars /cars?status=new /cars/123 /getAllCars /getAllNewCars /getCar/123
31. uses HTTP Verbs to perform operations on the elements
32. 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
33. returns meaningful errors
35. 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
36. 400 - 401 - 403 - 404 - 500 Bad Request Forbidden Unauthorized Not Found Internal Server Error
37. provides great support
38. Documentation
40. Documentation
41. Documentation Communication
42. Community Documentation Communication
43. is secure
44. what about versioning?
45. application/vnd.example.com+json; version=1 application/vnd.example.com.v1+json; Accept:
46. test the services? HOW TO define services contract? manage deployment?
47. ad$ A
50. contracts enable service independence
51. but…
52. " 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.
53. Contracts can also couple service providers and consumers
57. { "title": "App", "type": "object", "properties": { "name": { "type": "string", "title": "Name" }, "uris": { "type": "array", "title":"URIs", "items": { "type": "string" } } }, "required": ["name"] } required fields
58. { "links": [ { "href": "https://domain/apps", "method": "POST", "rel": “create”, "schema": { "$ref": "https://domain/schemas/apps/new_app" } } … ] }
59. Consumer-Driven Contracts: A Service Evolution Pattern http://martinfowler.com/articles/consumerDrivenContracts.html
60. test the services? HOW TO define services contract? manage deployment?
61. Deployment images search
62. Deployment search
63. Deployment
64. test the services? HOW TO define services contract? manage deployment?
66. Contract Tests Integration
 Tests
67. be positive
68. thanks! @albertoleal albertonb@gmail.com