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

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.

7a4bb535d5218b0ab4e92dd53618709c?s=128

Alberto Leal

April 24, 2014
Tweet

Transcript

  1. for DESIGNING THE APIS an internal set of services

  2. albertoleal albertonb@gmail.com

  3. None
  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

  34. None
  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

  39. None
  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

  48. None
  49. None
  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

  54. None
  55. None
  56. None
  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?

  65. None
  66. Contract Tests Integration
 Tests

  67. be positive

  68. thanks! @albertoleal albertonb@gmail.com