class: center, middle, section-title # Fake It Before<br/>You Make It: ## Mocking Your Way to <br/>Better HTTP APIs <br> <div style="width: 100%;"> <div style="width: 50%; float: left; display: inline-block;"> Ian Zelikman<br> ian.zelikman@gmail.com<br> @izcoder </div> <div style="width: 50%; display: inline-block;"> Dave Forgac<br> dave@forgac.com<br> @tylerdave </div> </div> </div> ??? - Welcome to Fake It Before You Make It: Mocking Your Way to Better HTTP APIs - First, I'm going to talk a bit about how you can use some modern tools and practices to improve your API development - Then Ian is going to give you a demonstration of how the process works. --- class: center, middle ## Slides, Examples, & More: ## BetterAPIs.com ??? - A copy of these slides, the sample code is available at betterapis.com - We also have links to more resources posted there --- class: center, middle, section-title # Terminology ??? - Before we get started I want to go over some terminology to make sure we're all using the same language - a lot of this will be review for many of you but just hang on and we'll get to the good stuff --- class: center, padded-top # REST ??? - When we talk about APIs we often use the term REST - REST is a *HUGE* topic - For our purposes you just need to know a few things -- ## ~~Standard~~ ??? - It's not a standard -- ## Architectural Style ??? - It's an architctural-style -- ## HTTP w/ Constraints ??? - A RESTful API is a service that uses HTTP with constraints on how it works: - Client-Server, Stateless, Cache, Interface / Uniform Contract, Layered System, Code-On-Demand -- ## REST-inspired HTTP APIs ??? - Many APIs don't fully adhere to these constraints - But they do follow some of the patterns, most commonly - mapping HTTP methods to actions - mapping URL paths to resources or objects - So we're really talking about REST-like or REST-inspired HTTP APIs --- class: center, padded-top # JSON -- ## JavaScript Object Notation -- ``` { "things": [ "foo", "bar" ], "message": "Hello, World!" } ``` ??? - way to serialize object data so it can be sent between systems - here's a simple example --- class: center # JSON Schema -- ``` { "title": "Example Schema", "type": "object", "properties": { "displayName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] } ``` ??? - JSON schema is a standard specification for describing your data format - It is written in JSON itself - Used in data validation and automated testing --- class: center, padded-top # YAML -- ## Serialization format -- ## (More) human-readable -- ## Superset of JSON -- ## Broad Support ??? - YAML stands for YAML aint markup language - It's a serialization format - meant to be more readable than JSON - It's actually a superset of JSON and can be converted to JSON - It has broad language support so it's starting to be used in a lot of places --- class: center # 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. ... ``` ??? - here's an example yaml document --- class: middle, center, section-title # This Talk ??? - Idea for talk came about a couple years ago when we were working together - An internal client had a need for a new feature --- class: center, padded-top2 # Requirement ??? - they had a really simple requirement -- ## Accept POST ??? - accept a post to create a new record -- ## Return OK / validation errors ??? - If any of the fields were invalid, return a list of errors --- class: center, padded-top2 # Implementation ??? - so that's what we implemented -- ## Accept POST ??? - an endpoint that accepts a POST -- ## Return OK / validation errors ??? - and if anyting failed validation, we returned the errors - ok great, we deployed our change and asked the other team to test --- class: center, padded-top2 > “That's not really what we wanted.” ??? - we deployed our new implementation and asked them to test - they said that's not really what they wanted -- # 😒 ??? - ok then - so what was the problem? --- class: center ## The Difference **simplified example* .left-column[ ### We provided ``` { "valid": false, "errors": { "field_1": "too short" "field_2": "required", } } ``` ] .right-column[ ### They expected ``` { "valid": false, "errors": [ { "field": "field_1" "error": "too short", }, { "error": "required" "field": "field_2", } ] } ``` ] ??? - this is a simplified example - basically they were expecting a nested structure and we were producing a flatter structure --- class: center, padded-top2 # Can we do better? ??? - so then we started thinking about how we could avoid this situation next time - we didn't want to just let the clients dictate how the interfaces would work - What we needed was a way for us to design our APIs and get feedback early-on -- # 💡 ??? - that's when a concept we'd been hearing a lot about finally made sense --- class: center, middle, section-title # API Contract! # 📝 ??? - and that's the diea of the api contract --- class: center, padded-top # API Contract ??? - like a legal contracts it's an agreement between two parties -- ## Consumer ↔ Provider ??? - in this case the API consumer and producer or client and server - often it's negotiated -- ## Interface Specification ??? - contract includes technical specification of how requests & responses should work -- ## SLA, ToS, Limits, Pricing, etc. ??? - It also includes other parts of agreement like SLA, rate limits, pricing tiers, etc --- class: center, padded-top # API Specification ??? - an api specification is how you define the interface contract -- ## Machine Readable ??? - can be used by computers -- ## Requests / Responses ??? - it includes a description of how the requests and responses should work -- ## Basis of Contract ??? - serves as the basis of the overlal API contract --- class: center, padded-top # Spec Formats ??? - API specifications aren't a new idea -- ## WSDL ??? - If you ever workd with SOAP or XML-RPC you may have seen WSDL - it's a verbose XML format for describing how one of those APIs work -- ## WADL ??? - when REST-like APIs started to become popular a new format was developed called WADL - like WSDL it's verbose XML and generally not fun to work with --- class: center, padded-top # For REST(-like) APIs <h2><img alt="Swagger" src="img/swagger.png" width=75/>  <img alt="OpenAPI Specification" src="img/open_api.png" width=300/></h2> <h2><img alt="RAML" src="img/raml.png" width=300/></h2> <h2><img alt="API Blueprint" src="img/api_blueprint.png" width=300/></h2> ??? - luckily a new breed of specifications formats has been developed in more recent years - the most popular are swagger specification, which is in the process of being renamed the openapi specification - RAML, and API Blueprint - Each has taken a different approach but they all achieve the primary goal of defining APIs in a machine and human readable format - Let's take a quick look at each --- class: center, padded-top # OpenAPI Spec ## (fka Swagger) ??? - swagger specification is being renamed openapi specification -- ## JSON or YAML ??? - early versions were JSON and were generally generated from code annotations - recent versions support YAML as well so it's easier to use to model an api before you develop -- ## OpenAPI Initiative ??? - the development of the specification is being managed by the OpenAPI Initiative - which is a project within The Linux Foundation - version 3 is coming soon --- class: center ### 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: - application/json ``` ??? - this is a basic openapi specification document in YAML - you can see it starts by defining basic meta information about the API - and then defines general usage information like the host, schemes, and content types --- class: center ### 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 items: $ref: '#/definitions/Foo' ``` ??? - then further down the speicifcation file URL paths are defined - for each one accepted request methods are defined along with the potential responses - the last line contains a reference to a definition - these allow you to define common models once without repeating youself --- class: center ### 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 ``` ??? - and here we can see where the definition that was referenced above is actuall defined --- class: center, padded-top # RAML -- ## YAML Specification -- ## Modeling ??? - Stands for RESTful API modeling language but supports any web APIs that use HTTP constructs - Uses YAML to describe APIs - it was developed in reaction to swagger 1 with a focus on modeling APIs first --- class: center ### 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. ``` ??? - let's take a look at a RAML specification - starts with meta information about the API - and basic usage information like the openapi example --- class: center ### 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 ``` ??? - again like openapi spec you can define common objects that will be reused in the spec --- class: center ### 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 items: type: Foo ``` ??? - and then you define paths with their accepted method - and the request and response formats --- class: center, padded-top # API Blueprint ??? - a format that takes a different approach is api blueprint -- ## Documentation as Specification ??? - it was developed from the perspective of documentatin as the specification -- ## MarkDown + Extensions ??? - It's written in MarkDown with some extensions - There are some 3rd-party projects but best support for node & .net --- class: center ### 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   + Attributes (array[Foo]) ``` ??? - As you can see while the format is different the contents end up being about the same - You start with the basics about the API - the nice thing about this is without any changes you can already render this as decent documentation --- class: center ### API Blueprint (2/2) ``` # Data Structures   ## Foo (object) An example type of object   ### Properties + `name` (string, optional) + `score` (number, optional) ``` ??? - and like the other formats, commonly reused objects can be defined once and referenced --- class: center # Comparison ??? - how do you choose one? -- ## User-base ??? - all have decent user bases and active communities though openapi is the largest -- ## Tooling ??? - the tooling ecosystem is broader for swagger/openapi but because raml and blueprint are supported by single companies: - the tools that they produce are well-integrated -- ## Language Support ??? - comes down to which one suports your programming language or framework -- ## Recent Events ??? - then in the time since we proposed this talk and today a few things have changed - apiary, the company behind blueprint joined the openapi initiative and was later acquired by oracle - and mulesoft, the creator of RAML just a couple weeks ago announce that they too are joining the openapi initiative - it'll be interesting to keep an eye on these going-forward -- ## It Depends... ??? - like any decision - but at this point i'd say unless one of the specific tools for raml or blueprint fits your need - start with openapi spec first --- class: center, padded-top # Defining Spec ??? - how do you define a specification? -- ## Implementation First ??? - one way is to implement your API and then generate a spec - using either code annotations - or if you're using a supported framework via a tool -- ## Contract First ??? - the other way is to define the contract first, then develop - that's what we're doing -- ## Integrated ??? - we're using an integrated framework that includes the specification as part of the implementation - this ensures that the contract can never diverge from the implementation --- class: center, middle, section-title # Benefits ??? - Once you have a specification it's great to be able to share it with others who are developing the api or api clients - But what else can you do with the spec? --- class: center, middle # Documentation ??? - Rendered to HTML - Interactive or static - To PDF --- class: center, middle # Testing ??? - With a spec you can statically validate API code. Support varies by language / framework - You can also validate against a live API in a test environment or even in production using tools to inspect requests / responses - dredd --- class: center, middle # Code Generation ??? - Tooling to support building-out stub methods based on the spec - Again depends on language / framework --- class: center, middle # Mocking ??? - part of a framework - or stand-alone tool --- class: center, padded-top # *Almost Demo Time!* -- ## Integrated Framework ??? - ian's example is using one of the integrated frameworks -- ## Connexion (Python) -- ## Spec as Config: ### Routing ### Validation ### Serialization ??? - Once you have the specification and tooling in place you can first focus on defining your API contracts by: - desiging, getting feedback, and interating until it's agreed - Then you can implement and there will be no surprises --- <div> <h1>Fake it ➡ Make it</h1> <div style="width: 100%;"> <div style="width: 49%; float: left; display: inline-block;" class="fragment"> <h3>Spec</h3> <p>Write / Update</p> <p>Mock</p> <p>Publish</p> </div> <div style="width: 49%; display: inline-block;" class="fragment"> <h3>API</h3> <p>Implement</p> <p>Validate</p> </div> </div> ??? --- class: center, middle, demo # Demo --- class: center, padded-top # Tooling -- ## Frameworks -- ## Mocking -- ## Validation / Testing --- class: center, middle # Resources ## BetterAPIs.com ## Further Reading ??? - I just wanted to note that there are links to a few resources at the end of the slides that will be online - More background on API contracts - Comparison of specs - Link to a converter --- class: center, middle, section-title # Thank You! <br> ### *Please leave feedback!* ### "Rate This Session" on schedule listing <br> <div style="width: 100%;"> <div style="width: 50%; float: left; display: inline-block;"> Ian<br> ian.zelikman@gmail.com<br> @izcoder </div> <div style="width: 50%; display: inline-block;"> Dave<br> dave@forgac.com<br> @tylerdave </div> </div> </div>