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
   

   View Slide

2. Slides, Examples, & More:
   BetterAPIs.com
   

   View Slide

3. Terminology
   

   View Slide

4. REST
   

   View Slide

5. REST
   Standard
   

   View Slide

6. REST
   Standard
   Architectural Style
   

   View Slide

7. REST
   Standard
   Architectural Style
   HTTP w/ Constraints
   

   View Slide

8. REST
   Standard
   Architectural Style
   HTTP w/ Constraints
   REST-inspired HTTP APIs
   

   View Slide

9. JSON
   

   View Slide

10. JSON
    JavaScript Object Notation
    

    View Slide

11. JSON
    JavaScript Object Notation
    {
    "things": [
    "foo",
    "bar"
    ],
    "message": "Hello, World!"
    }
    

    View Slide

12. JSON Schema
    

    View Slide

13. JSON Schema
    {
    "title": "Example Schema",
    "type": "object",
    "properties": {
    "displayName": {
    "type": "string"
    },
    "age": {
    "description": "Age in years",
    "type": "integer",
    "minimum": 0
    }
    },
    "required": ["firstName", "lastName"]
    }
    

    View Slide

14. YAML
    

    View Slide

15. YAML
    Serialization format
    

    View Slide

16. YAML
    Serialization format
    (More) human-readable
    

    View Slide

17. YAML
    Serialization format
    (More) human-readable
    Superset of JSON
    

    View Slide

18. YAML
    Serialization format
    (More) human-readable
    Superset of JSON
    Broad Support
    

    View Slide

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

    View Slide

20. This Talk
    

    View Slide

21. Requirement
    

    View Slide

22. Requirement
    Accept POST
    

    View Slide

23. Requirement
    Accept POST
    Return OK / validation errors
    

    View Slide

24. Implementation
    

    View Slide

25. Implementation
    Accept POST
    

    View Slide

26. Implementation
    Accept POST
    Return OK / validation errors
    

    View Slide

27. “That's not really what we wanted.”
    

    View Slide

28. “That's not really what we wanted.”
    

    View Slide

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
    

    View Slide

30. Can we do better?
    

    View Slide

31. Can we do better?
    

    View Slide

32. API Contract!
    

    View Slide

33. API Contract
    

    View Slide

34. API Contract
    Consumer ↔ Provider
    

    View Slide

35. API Contract
    Consumer ↔ Provider
    Interface Specification
    

    View Slide

36. API Contract
    Consumer ↔ Provider
    Interface Specification
    SLA, ToS, Limits, Pricing, etc.
    

    View Slide

37. API Specification
    

    View Slide

38. API Specification
    Machine Readable
    

    View Slide

39. API Specification
    Machine Readable
    Requests / Responses
    

    View Slide

40. API Specification
    Machine Readable
    Requests / Responses
    Basis of Contract
    

    View Slide

41. Spec Formats
    

    View Slide

42. Spec Formats
    WSDL
    

    View Slide

43. Spec Formats
    WSDL
    WADL
    

    View Slide

44. For REST(-like) APIs
    

    View Slide

45. OpenAPI Spec
    (fka Swagger)
    

    View Slide

46. OpenAPI Spec
    (fka Swagger)
    JSON or YAML
    

    View Slide

47. OpenAPI Spec
    (fka Swagger)
    JSON or YAML
    OpenAPI Initiative
    

    View Slide

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:
    

    View Slide

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
    

    View Slide

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
    

    View Slide

51. RAML
    

    View Slide

52. RAML
    YAML Specification
    

    View Slide

53. RAML
    YAML Specification
    Modeling
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

57. API Blueprint
    

    View Slide

58. API Blueprint
    Documentation as Specification
    

    View Slide

59. API Blueprint
    Documentation as Specification
    MarkDown + Extensions
    

    View Slide

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
    

    View Slide

61. API Blueprint (2/2)
    # Data Structures
    ## Foo (object)
    An example type of object
    ### Properties
    + `name` (string, optional)
    + `score` (number, optional)
    

    View Slide

62. Comparison
    

    View Slide

63. Comparison
    User-base
    

    View Slide

64. Comparison
    User-base
    Tooling
    

    View Slide

65. Comparison
    User-base
    Tooling
    Language Support
    

    View Slide

66. Comparison
    User-base
    Tooling
    Language Support
    Recent Events
    

    View Slide

67. Comparison
    User-base
    Tooling
    Language Support
    Recent Events
    It Depends...
    

    View Slide

68. Defining Spec
    

    View Slide

69. Defining Spec
    Implementation First
    

    View Slide

70. Defining Spec
    Implementation First
    Contract First
    

    View Slide

71. Defining Spec
    Implementation First
    Contract First
    Integrated
    

    View Slide

72. Benefits
    

    View Slide

73. Documentation
    

    View Slide

74. Testing
    

    View Slide

75. Code Generation
    

    View Slide

76. Mocking
    

    View Slide

77. Almost Demo Time!
    

    View Slide

78. Almost Demo Time!
    Integrated Framework
    

    View Slide

79. Almost Demo Time!
    Integrated Framework
    Connexion (Python)
    

    View Slide

80. Almost Demo Time!
    Integrated Framework
    Connexion (Python)
    Spec as Config:
    Routing
    Validation
    Serialization
    

    View Slide

81. Spec
    Write / Update
    Publish
    Mock
    Fake it ➡ Make it
    API
    Implement
    Validate
    

    View Slide

82. Demo
    

    View Slide

83. Tooling
    

    View Slide

84. Tooling
    Frameworks
    

    View Slide

85. Tooling
    Frameworks
    Mocking
    

    View Slide

86. Tooling
    Frameworks
    Mocking
    Validation / Testing
    

    View Slide

87. Resources
    BetterAPIs.com
    Further Reading
    

    View Slide

88. Ian
    ian.zelikman@gmail.com
    @izcoder
    Thank You!
    Please leave feedback!
    "Rate This Session" on schedule listing
    Dave
    dave@forgac.com
    @tylerdave
    

    View Slide