A presentation at POST/CON 2019 in in San Francisco, CA, USA by Kaustav Das Modak
Design, Develop & Mock APIs with Postman PRESENTED BY Kaustav Das Modak Developer Advocate, Postman @kaustavdm
Concepts • Real-life API collaboration • API Design: What we need • Postman fundamentals What we will cover Role: Producer • Creating collections and Mocks • Using “API” and schema Role: Consumer • Using Mocks • Collaborating with producer
Part 1: Concepts
Let’s talk about APIs
Applications today are built of multiple interacting components APIs are the building blocks of modern software. Multiple services, spanning multiple teams and multiple geographical regions. Developing those services in parallel without teams blocking others is a challenge that teams face often.
When systems talk to each other, we should carefully design how they interact In a world where systems talk to each other, it is vital to carefully design how these systems will interact. It is terribly easy to get lost in the quagmire of multiple services and multiple dependencies and who does whom.
Design your APIs before you implement them In a world where systems talk to each other, it is vital to carefully design how these systems will interact. Instead of the traditional code-first approach to software development, API-first development is a software development pattern which asks you to design and scope out your APIs before you build the software.
Agree on domain boundaries and data models before you implement them Gist of API-first design Allows stakeholders to add their inputs.
Agree on domain boundaries and data models before you implement them Collaborate
Business use case Abstraction Encapsulation Agree on domain boundaries and data models before you implement them Collaborate
Business use case Abstraction Encapsulation Entities Resources Data structures Agree on domain boundaries and data models before you implement them Collaborate
Data models Code Design Implementation Business logic Publish Separating the design of the API from its implementation, the architect is constrained only by the data model and business logic. Your API can now evolve unfettered by any existing user interface or legacy engineering frameworks.
A good design should adapt to changes Caveat: Make sure you design APIs in a way that they remain flexible to future changes.
Key concepts
If you work with APIs…
What is an API? When people talk about APIs, sometimes they talk about the implementation or the code, sometimes they’re referring to the interface, and sometimes they’re referring to the hosted version of the service.
What is an API? Interface Schema OpenAPI RAML GraphQL Postman
What is an API? Interface Implementation Schema OpenAPI RAML GraphQL Postman Code Databases Repositories Microservices …
What is an API? Interface Implementation Instance Schema OpenAPI RAML GraphQL Postman Code Databases Repositories Microservices … Deployed Interface + Implementation + Servers …
What is an API? Interface Implementation Instance Schema OpenAPI RAML GraphQL Postman Code Databases Repositories Microservices … Deployed Interface + Implementation + Servers …
What is an API? Interface Implementation Instance Schema OpenAPI RAML GraphQL Postman Code Databases Repositories Microservices … Deployed Interface + Implementation + Servers …
Producer Consumer Roles Producer: Who builds and serves an API Consumer: Who uses that API for their work
Producer Consumer Requirements Roles
Resources Producer Consumer Requirements Roles
Private Partner Scopes Arrow follows more number of potential consumers Public
More potential consumers Private Partner Scopes Public
Schema Callout: How many of these have you worked with? Any ones that you know are missing from this list?
OpenAPI 2.0 | 3.0 GraphQL RAML WSDL API Blueprint Schema Postman Collections
Questions to ask Producers How do we gather requirements? How do we share API docs? How do we collect feedback? Consumers How do we give our inputs? How do we consume docs? How do we test our requirements?
Design the interface Write API schema Build a testable, executable spec Collaborate on decisions What we need for effective API design Document the interface Resource & usage descriptions Request/Response examples Collaborate on implementation API Mocks API Contracts
What is the single source of truth?
Part 2: Setting things up
GET postman.com Make sure you have the latest version of Postman app installed Create account. Signin.
What we will build today Design API for a hypothetical service to manage list of cats. As both producer and consumer. We will focus on the API interface design. Not the code for actually building the service. In the process we will use Postman’s Mock Servers to serve as a backend.
Routes: v0.1
Routes (new): v0.2
Part 3: Postman fundamentals A quick overview of the Postman features we will need to build the rest
Collections Group and organize your requests into meaningful collections.
Variables Foundation of dynamic values for requests. Can be manipulated programmatically.
Workspaces • Organised by service and function • Service producers and consumers share their collections in them Workspaces form the foundation of collaboration for our teams.
Pre-request Script • Written in JavaScript • Executed in a sandboxed NodeJS environment • Executed before request is sent • Modify request through variables Every single request can have tests. Foreshadowing: Just like variables, tests can also be written at collection and folder levels.
Tests • Written in JavaScript • Executed in a sandboxed NodeJS environment • Executed after response is received • Can have assertions • Quick-start snippets Every single request can have tests. Foreshadowing: Just like variables, tests can also be written at collection and folder levels.
Postman API Programmatically interact with elements in the Postman ecosystem api.getpostman.com
Blueprints • Collections created by service producers to describe an API • Includes examples of each request to document responses Collections that serve as API reference Provides request and response structure (Usually) First piece in the design phase of an API
Mock servers • Created by service producers from blueprint collections • Used by service consumers to test API contracts More on contracts later.
Comments • To make contextual comments and tag other team members in collections, in the app, and in the browser • Used to negotiate API design among stakeholders One of the newer features in Postman Comments in collections make discussions contextual. Postman is invested in improving this feature. Again, dogfooding here helps us understand the scopes for improvement.
Questions? (and a quick break)
Part 4: Role - API Producer
• Create blueprint collection • • Build a blueprint collection • Add requests • Add documentation • Add examples • Success cases • Failure cases Share collection in Workspace Comments on requests
Create Mock Server • • • What is a Mock Server? (Recap) Create a mock server from Blueprint collection Execute Blueprint collection against Mock
Create “API” and schema • • Create a new “API” Add OpenAPI 3.0 YAML schema • From: bit.ly/postman-api-yaml • File: api-v0.1.yaml
Use versioning • • Edit API version tag to v0.1 Add blueprint collection and mock to API v0.1
Questions? (and another quick break)
Part 5: Role - API Consumer
• Using Mocks as a consumer • • • • Build contract collection based on blueprint collection Send requests to Mock endpoint Save and document requests Add tests to assert on response Switch base URL using environments
Part 6: Work with versions
• • Create v0.2 • • • Create v0.2 for the API Update OpenAPI schema • From: bit.ly/postman-api-yaml • File: api-v0.2.yaml Update blueprint Update contract Tag collections with new version
Questions? (and we’re done!)
Thank you! @postmanclient @kaustavdm betterpractices.dev
Learn how to collaboratively plan and design APIs to establish a single source of truth for your API lifecycle. This workshop will focus on building Collections to represent APIs from the point of view of both producers and consumers of an API.
We will show how you can use API schemas (OpenAPI/RAML/GraphQL) in Postman, manage versions of collections, and document them. We will also deep-dive into Mock Servers, and show how you can use them in your development.
The following resources were mentioned during the presentation or are useful additional information.
Postman Collection build during the workshop
As more organizations move to the cloud, they implement processes to deal with new microservices architectures, containerization, and continuous delivery. Whether they’re adopting cloud services or transitioning to a cloud infrastructure, an API-first approach can help you manage the complexity of working in the cloud.
Here’s what was said about this presentation on social media.
for free. You
can too.