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

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