OSCON 2017 - Fake It Before You Make It: Mocking Your Way to Better HTTP APIs

Transcript

1. Ian Zelikman ian.zelikman@gmail.com @izcoder Fake It Before You Make It: Mocking Your Way to Better HTTP APIs Dave Forgac dave@forgac.com @tylerdave
2. Slides, Examples, & More: BetterAPIs.com
3. Terminology
4. REST
5. REST Standard
6. REST Standard Architectural Style
7. REST Standard Architectural Style HTTP w/ Constraints
8. REST Standard Architectural Style HTTP w/ Constraints REST-inspired HTTP APIs
9. JSON
10. JSON JavaScript Object Notation
11. JSON JavaScript Object Notation { "things": [ "foo", "bar" ], "message": "Hello, World!" }
12. JSON Schema
13. JSON Schema { "title": "Example Schema", "type": "object", "properties": { "displayName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
14. YAML
15. YAML Serialization format
16. YAML Serialization format (More) human-readable
17. YAML Serialization format (More) human-readable Superset of JSON
18. YAML Serialization format (More) human-readable Superset of JSON Broad Support
19. YAML Example --- talk: title: Fake It Before You Make It subtitle: Mocking Your Way to Better HTTP APIs topics: - apis - development bio: > A talk about defining API contracts before developing implementations. ...
20. This Talk
21. Requirement
22. Requirement Accept POST
23. Requirement Accept POST Return OK / validation errors
24. Implementation
25. Implementation Accept POST
26. Implementation Accept POST Return OK / validation errors
27. “That's not really what we wanted.”
28. “That's not really what we wanted.”
29. We provided { "valid": false, "errors": { "field_1": "too short" "field_2": "required", } } They expected { "valid": false, "errors": [ { "field": "field_1" "error": "too short", }, { "error": "required" "field": "field_2", } ] } The Difference *simplified example
30. Can we do better?
31. Can we do better?
32. API Contract!
33. API Contract
34. API Contract Consumer ↔ Provider
35. API Contract Consumer ↔ Provider Interface Specification
36. API Contract Consumer ↔ Provider Interface Specification SLA, ToS, Limits, Pricing, etc.
37. API Specification
38. API Specification Machine Readable
39. API Specification Machine Readable Requests / Responses
40. API Specification Machine Readable Requests / Responses Basis of Contract
41. Spec Formats
42. Spec Formats WSDL
43. Spec Formats WSDL WADL
44. For REST(-like) APIs
45. OpenAPI Spec (fka Swagger)
46. OpenAPI Spec (fka Swagger) JSON or YAML
47. OpenAPI Spec (fka Swagger) JSON or YAML OpenAPI Initiative
48. Swagger / OpenAPI Spec 2.0 (1/3) swagger: '2.0' info: version: '1.0.0' title: Fake Better API description: > This is a basic example API for our talk at http://betterapis.com. termsOfService: http://betterapis.com/terms/ contact: name: API Team email: apiteam@betterapis.com url: http://betterapis.com/contact/ host: api.betterapis.com basePath: / securityDefinitions: {} schemes: - http consumes: - application/json produces:
49. Swagger / OpenAPI Spec 2.0 (2/3) paths: /foo: get: operationId: listFoo produces: - application/json parameters: - name: limit in: query required: false default: 10 type: integer format: int32 description: maximum number of foo to return responses: 200: description: List all foo schema: type: array
50. Swagger / OpenAPI Spec 2.0 (3/3) definitions: Foo: title: Foo description: An example type of object type: object properties: name: type: string score: type: integer format: int32
51. RAML
52. RAML YAML Specification
53. RAML YAML Specification Modeling
54. RAML (1/3) #%RAML 1.0 title: Fake Better API version: 1.0.0 baseUri: http://api.betterapis.com/ baseUriParamaters: {} documentation: - title: Fake Better API content: This is a basic example API for our talk at http://betterapis.com.
55. RAML (2/3) types: Foo: displayName: Foo description: An example type of object type: object properties: name: required: false displayName: name type: string score: required: false displayName: score type: integer format: int32
56. RAML (3/3) /foo: get: displayName: listFoo queryParameters: limit: required: false default: 10 displayName: limit description: maximum number of foo to return type: integer format: int32 responses: 200: description: List all foo body: application/json: displayName: response description: List all foo type: array
57. API Blueprint
58. API Blueprint Documentation as Specification
59. API Blueprint Documentation as Specification MarkDown + Extensions
60. API Blueprint (1/2) FORMAT: 1A HOST: http://api.betterapis.com/ # Fake Better API This is a basic example API for our talk at http://betterapis.com. # Foo [/foo{?limit}] ## listFoo [GET] + Parameters + limit (number, optional) - maximum number of foo to return + Default: 10 + Response 200 (application/json) List all foo
61. API Blueprint (2/2) # Data Structures ## Foo (object) An example type of object ### Properties + `name` (string, optional) + `score` (number, optional)
62. Comparison
63. Comparison User-base
64. Comparison User-base Tooling
65. Comparison User-base Tooling Language Support
66. Comparison User-base Tooling Language Support Recent Events
67. Comparison User-base Tooling Language Support Recent Events It Depends...
68. Defining Spec
69. Defining Spec Implementation First
70. Defining Spec Implementation First Contract First
71. Defining Spec Implementation First Contract First Integrated
72. Benefits
73. Documentation
74. Testing
75. Code Generation
76. Mocking
77. Almost Demo Time!
78. Almost Demo Time! Integrated Framework
79. Almost Demo Time! Integrated Framework Connexion (Python)
80. Almost Demo Time! Integrated Framework Connexion (Python) Spec as Config: Routing Validation Serialization
81. Spec Write / Update Publish Mock Fake it ➡ Make it API Implement Validate
82. Demo
83. Tooling
84. Tooling Frameworks
85. Tooling Frameworks Mocking
86. Tooling Frameworks Mocking Validation / Testing
87. Resources BetterAPIs.com Further Reading
88. Ian ian.zelikman@gmail.com @izcoder Thank You! Please leave feedback! "Rate This Session" on schedule listing Dave dave@forgac.com @tylerdave