Design, Develop and Mock APIs with Postman (Workshop)

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 …

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

GET /cats Returns list of all cats - POST /cats Add a new cat Cat schema: - id: Integer name: String breed: String age: Integer

Routes (new): v0.2

GET /cats/{{catId}} Find a specific cat

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