Full Chapter Designing Apis With Swagger and Openapi Meap V04 Joshua S Ponelat Lukas L Rosenstock PDF

Designing APIs with Swagger and
OpenAPI MEAP V04 Joshua S Ponelat

Lukas L Rosenstock
Visit to download the full and correct content document:
https://textbookfull.com/product/designing-apis-with-swagger-and-openapi-meap-v04-
joshua-s-ponelat-lukas-l-rosenstock/
More products digital (pdf, epub, mobi) instant
download maybe you interests ...
Five Lines of Code MEAP V04 Christian Clausen
https://textbookfull.com/product/five-lines-of-code-
meap-v04-christian-clausen/
Apache Pulsar in Action MEAP V04 David Kjerrumgaard
https://textbookfull.com/product/apache-pulsar-in-action-
meap-v04-david-kjerrumgaard/
Spring in Action - Sixth Edition (MEAP V04) Craig Walls
https://textbookfull.com/product/spring-in-action-sixth-edition-
meap-v04-craig-walls/
Domain Specific Languages Made Easy MEAP V04 Meinte

Boersma
https://textbookfull.com/product/domain-specific-languages-made-
easy-meap-v04-meinte-boersma/
Machine Learning Engineering in Action MEAP V04 Ben T
Wilson
https://textbookfull.com/product/machine-learning-engineering-in-
action-meap-v04-ben-t-wilson/
Microservices in NET Core Second Edition MEAP V04

Christian Horsdal Gammelgaard
https://textbookfull.com/product/microservices-in-net-core-
second-edition-meap-v04-christian-horsdal-gammelgaard/
Designing Web APIs Building APIs That Developers Love

First Edition Jin
https://textbookfull.com/product/designing-web-apis-building-
apis-that-developers-love-first-edition-jin/
Shut Up and Run How to Get Up Lace Up and Sweat with

Swagger Robin Arzon
https://textbookfull.com/product/shut-up-and-run-how-to-get-up-
lace-up-and-sweat-with-swagger-robin-arzon/
Management Control with Integrated Planning Models and

Implementation for Sustainable Coordination Lukas
Rieder
https://textbookfull.com/product/management-control-with-
integrated-planning-models-and-implementation-for-sustainable-
coordination-lukas-rieder/
MEAP Edition
Manning Early Access Program
Designing APIs with Swagger and OpenAPI
Version 4
Copyright 2020 Manning Publications
For more information on this and other Manning titles go to

manning.com
©Manning Publications Co. To comment go to liveBook

welcome
Thank you for purchasing the MEAP of Designing APIs with Swagger and OpenAPI!
My name is Josh Ponelat ( Pah-neh-lat ) and I have the privilege of introducing you to the
world of OpenAPI and Swagger. The eco-systems that surround RESTful APIs and the
sheer joy of leveraging and automating those systems.
The goal of this book is to teach the fundamentals of describing APIs using OpenAPI,
and how those descriptions can be used to drive parts of your work flows and pipelines with
tooling, such as those prefixed with Swagger.
Within you'll find out how to read and write OpenAPI definitions, where writing consists
of describing existing or new RESTful APIs. We'll disambiguate as much as we can, aiming
to answer questions as to "why" something is the way it is. After literacy of OpenAPI, we'll
dive into the design process. How to create new APIs cheaply and iterate on their design.
And finally we'll look at some lovely advanced topics, including my favourite.. guidelines to
building your own OpenAPI tooling.
OpenAPI and Swagger are both Open Source, and there are resources on the subjects
online, but few books to capture just how they work and why they're so sorely needed today.
While I've endeavoured to do just that, I'd like to ask for your help.
Please reach out in the liveBook's discussion forum and comments, the biggest help can
come from silly questions, such as asking for clarity on a subject or even just asking why
something happens to be that way.
Ultimately by learning the fundamentals of OpenAPI and Swagger, my hope is that this
book will make your life a little easier and hopefully even inspire you to automate even
more things!
—Joshua S. Ponelat

brief contents
PART 1
1 Introducing APIs and OpenAPI
2 Getting set up to make API requests
3 Our first taste of OpenAPI definitions
4 Using Swagger Editor to write OpenAPI definitions
5 Describing API responses
6 Creating resources
7 Adding Authentication and Authorization
8 Preparing and hosting API documentation
PART 2
9 Designing a web application
10 Creating an API design using OpenAPI
11 Building a change workflow around API Design First
12 Implementing frontend code and reacting to changes
13 Building a backend with Node.js and Swagger Codegen
14 Integrating and releasing the web application
15 Reviewing our plan and design strategy
PART 3
16 Designing the next API iteration
17 Versioning an API and handling breaking changes
18 Scaling collection endpoints with filters and pagination
19 Supporting the unhappy path: error handling with problem+json
20 Improving input validation with advanced JSON Schema
21 Beyond the application: what's next for our API?
PART 4
22 Composition of API definitions
23 Swagger 2.0 vs OpenAPI 3.0 vs OpenAPI 3.1
24 Building your own tools for OpenAPI
25 Enter OAuth: Securing an API for public usage
26 Deploying an API Gateway
27 Using OpenAPI for API testing and monitoring

1
This chapter covers:

Introducing APIs and OpenAPI
1
Describing an API Ecosystem
What OpenAPI and Swagger are
When to use OpenAPI
An overview of this book
In this chapter we’ll take a look at the world of APIs and OpenAPI, so that we can get
comfortable with the topics of this book. We’ll start by taking a look at the benefits of describing
an API, how it forms part of an API ecosystem and where OpenAPI fits in. We’ll look at an
example of an OpenAPI document and when to use OpenAPI in practice.
Lets get started…
1.1 What is an API Ecosystem?

I like the word ecosystem. It describes the interactions and relationships between living and
non-living within a fully functioning environment. I always picture a wetland pond with frogs,
wild grasses and stones for some reason, but you may imagine something a little different - either
way the principle of an interactive symbiotic system remains.
If we were to borrow (cough maybe steal ) this principle from biology we could use it to
describe the world of APIs within a team or organization.
The living, changing variables would represent elements that we have control over. These are the
things we make such as our services, stacks or code. The fixed, non living components would

https://livebook.manning.com/#!/book/designing-apis-with-swagger-and-openapi/discussion
2
then be the useful things we can benefit from but cannot easily change. These are the libraries
and external services we use. And of course there is the environment. It could be the Internet, an
internal network or a tiny device stuck on the roof of our house. Perhaps even all of them!
All of these pieces put together forms a complete ecosystem. When these parts are moving in
harmony then our system is healthy and our developers/consumers/users are all happy.
APIs tie together these disparate services, forming the foundation of the ecosystem. When we
assume the role of an "API designer", then our job is to create contracts for services, incorporate
feedback from consumers and ensure changes are communicated ahead of time.
Why API Ecosystem and not Service Ecosystem or perhaps even just Ecosystem you might ask?
That’s a reasonable question, and the answer would depend on which we choose to focus on. In
this book we’re interested in APIs so naturally we focus on that aspect. Since APIs are the
contracts that hold together the ecosystem it is not an unreasonable focal point. This is in fact a
very important part of the ecosystem, without which our services are all isolated. Understanding
them gives us a wholistic perspective.
This book is going to focus on the APIs and the contracts that define, or describe them.
1.2 Describing things

When we look at our ecosystem as individual aspects of a multitude of connections, we might
wonder at what each aspect truly means, what it’s comprised of, and how each one fits into this
design. The how part is where all the interesting bits are.
When those services change without updating all of their dependencies the ecosystem loses
functionality and in some cases can completely break.
Let’s take a look at this story, for example.
1.2.1 Bridget’s Task

Bridget has been tasked to manage a medium sized web stack. Her stack (or ecosystem) is made
up of services that talk to, and depend on each other. The stack also makes use of external
services which are beyond her control.
Every now and then one of the APIs will change in such a way as to negatively impact, and
sometimes break the services that rely on it. This disrupts the ecosystem, bringing down parts of
her stack and ultimately causing failures.
Bridget will need to effectively solve this problem, therefore when an API changes she needs to
tell the affected developers beforehand and keep the ecosystem running smoothly.

3
Bridget takes a moment to think about how this ecosystem works, by breaking it down into
tangible steps. She knows that each service has an API, and that each of those APIs are made up
of smaller operations. Each operation expects a certain input and generates an equal resulting
output. When an operation changes so that it requires different inputs , any service that doesn’t
evolve and adapt along with it will result in a systemic failure.
In the same way, when an operation produces a different output, it will cause other dependent
services to break unless they update to address those changes.
Bridget knows that if an API changes its operations to expect different inputs or produce
different outputs, then her ecosystem will suffer.
She concludes that tracking those changes is an important part of keeping functionality up, but
how will she know when an API has changed?
Bridget decides she needs a way of describing APIs, so that she can compare an old API with a
new API, in order to see if the new one has any breaking changes. She writes a program that
takes a description of an API and compares the older version with a newer version - generating a
report. The report is simple and tells her if the new API has any breaking changes from the old.
Happy with her plan, she instructs the developers to describe their APIs in her format so that she
can continue to compare old with new. Aware that the external services aren’t under control, she
keeps an eye on any developments and describes it herself- she is prepared for when those
external services change.
1.2.2 The potential of Bridget’s solution

Bridget’s solution to her problem is centered around the idea that you can describe your APIs in
such a way that people can write them and software can understand them.
While she only used that approach to solve one specific problem, there is now much more
potential for growth with those descriptions. They can serve as the basis for generating more than
just reports. For example she could generate documentation, test out changes before building
them, reduce the overhead of boilerplate code and much more.
Given the title of this book, the punchline may be a little ruined. But let us take a look at how
Bridget’s solution is used in the real world. Let’s take a look at how OpenAPI works…
1.3 What is OpenAPI?

OpenAPI is a description of HTTP-based APIs which are typically, RESTful APIs. It comes in
the form of a YAML file or definition, that describes the inputs and outputs of an API. It can also
include information such as where the API is hosted, what authorization is required to access it,
and other details needed for consumers and producers (such as web-developers).
4
Definitions can be written by hand, by tools, or even generated from code. Once an API has been
written down we say it has been described. Once API has been described into a definition, it
becomes a platform for tools and humans to make use of. A typical example of making use of
API definitions is to generate human readable documentation from it.
1.3.1 Example OpenAPI Definition

There is a fun little API for dog breeds and their images on the Internet hosted at dog.ceo. To
give you an example of what an OpenAPI definition looks like, I’ve described a single operation
from this dog API, along with some other basic details of the API. Here is that definition ( as a
YAML file )…
Listing 1.1 Example OpenAPI Document/Definition

openapi: 3.0.0
info:
title: Dog API
version: 1.0.0
servers:
- url: https://dog.ceo/api
paths:
/breed/{breedName}/images:
get:
description: Get images of dog breeds
parameters:
- in: path
name: breedName
schema:
type: string
example: hound
required: true
responses:
'200':
description: A list of dog images
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
message:
type: array
items:
type: string
example: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
It can be a little verbose at first glance, but you will find some exceptionally useful information
contained within.
From it, we can gather a few snippets about the single operation it describes and how to consume
it.
The API is hosted at dog.ceo/api

There is a GET operation: GET /breed/{breedName}/images
5
Where the breedName in the URI, is a string

We see that a successful response will give us a JSON array where each item is an object
containing the message and status fields.
The message fields is an array of strings which are URLs of dog images.
That is usable information. Developers can build clients to consume the API, product managers
can determine if the API suits their needs and meets their standards, and documentation teams
can use it as the basis for showing human readable documentation.
As an example of using an OpenAPI definition, we can load this definition into a tool called
SwaggerUI (we’ll go into details of that later in the book). It will render documentation based on
the definition and provide other small niceties. It would look something like the following…
Figure 1.1 SwaggerUI with Dogs API
SwaggerUI can consume the API definition file and from it render a more human friendly
version of it.
1.4 Where do OpenAPI definitions fit in ?

Once we have an API definition we use tools to leverage them, build bigger abstractions and
more automated work flows.
Here is a diagram showing how OpenAPI definitions could fit into an organization’s work flows.

6
Figure 1.2 OpenAPI
The diagram shows how to leverage OpenAPI definitions, that are described by tools or by
extracting annotations from code. They are then transformed into API documentation, server
stubs / routers and client SDKs. There are certainly more work flows that could be diagrammed
out, ones that provide more specific value depending on the business cases.
Other work flows could include…
Example Workflows:
Automating parts of testing (APIs)

Getting early feedback on the design of the API
Ensuring API consistency
Comparing API changes across versions, etc.
The beauty of OpenAPI is that, once you have an OpenAPI definition, the rest (pun!) is simply a
matter of leveraging it for your needs.

7
1.5 And what is Swagger?

In the beginning there was SwaggerUI and a rough guide for writing YAML files that described
HTTP APIs. Later, more tools were built that relied on this guide that soon became a
specification and a standard. The tools and this specification were collectively known as
"Swagger". The term referred to all of it. The specification grew more mature and was released
as open source encouraging the community to create even more tools. They soon began to
contribute features into the specification, which finally began to be adopted by large companies
and house hold names.
Then in 2015 it was adopted by SmartBear who then donated the specification part to the Linux
Foundation1. During that transfer the specification part was subsequently renamed to the
OpenAPI Specification and SmartBear retained the copyright for the term Swagger.
Today you’ll find the terms used interchangeably as a result of this historical quirk. Going
forward its encouraged to use the term OpenAPI to refer the heart of this ecosystem: the
specification. And to use Swagger to refer to the specific set of tools managed by SmartBear (
which includes SwaggerUI, SwaggerEditor, SwaggerParser and at least a dozen more ).
1.6 What about REST?

REST or REpresentational State Transfer is a collection of ideas around how to design
networked systems (in particular server/client systems), and while it is not restricted to HTTP
based APIs they are both closely linked in practice.
The principles of REST were outlined by Roy Fielding in his dissertation on networked systems
which was released in the year 2000. RESTful APIs now drive the majority of web servers on the
Internet and what makes an API RESTful is determined by how closely it adopts the ideas ( or
constraints ) of that dissertation. 2 and can be considered a little subjective. Out in the wild
HTTP-based APIs have to make trade offs between what they require, and how standard or
RESTful they wish to be. It is a balancing act for all API producers to juggle.
The ideas in REST aim to be simple, and to decouple the API from the underlying services that
serve the API. It has a request/response model and is stateless, as all the information necessary to
do something is contained within the request.
One of the key ideas behind REST is the idea of a resource. I like to think of them as boxes that
you can put things into. Things such as user accounts, billing reminders or even the weather in
San Francisco, all of these things are resources. Resources are identified by a URI. For a user’s
account we might have /users/123 where 123 is the identifier for that user.
Given a resource, consumers will want to be able to do things to and with them. Think of these
actions as verbs. HTTP has a set of well defined ones, such as
8
POST,GET,PUT,DELETE,PATCH and a few less common ones. These are HTTP methods but
they are derived from the ideas in REST. As an example of a HTTP method, if you wish to fetch
data related to a resource you would use the GET method. If you wish to create a new resource
you could use the POST method.
Where REST starts and HTTP ends is a tricky one to answer, but the rule of thumb is HTTP is
the actual protocol and REST is a way of designing APIs. HTTP has incorporated many of the
ideas of REST into its protocol, which is why they are so closely related.
Typically we’ll more often note when a HTTP API is not RESTful, by that we mean it doesn’t
conform to the design patterns outlined by REST.
OpenAPI was designed to describe as many HTTP based API as possible, but not all of them. Its
major constraint ( and a huge benefit of OpenAPI ) is to still allow tools to generate usable code
from the definitions, this means that some API nuances may not be describable in OpenAPI.
NOTE A quick note regarding Hypermedia.

In Roy’s REST paper he mentions the idea of Hypermedia. A system of
returning context aware links, in the form of URIs. For example, If you were
to execute a GET on a /users/{userId} resource it could return a link (
URI ) to execute a password reset. Another link might be to the login
operation for that user. The links are related to resource ( at that point in
time ) and decouple clients from knowing those URIs outside of the
response. This is a crude description of a very powerful model.
Many REST purists are eager to point out that this is a sorely missed
component of RESTful APIs. In OpenAPI ( particularly v3.0.0+ ) support
was added to help document these hypermedia links, but their semantics
are out of scope for the OpenAPI specification.
OpenAPI is sufficient to describe what is required by Hypermedia APIs
but not the semantics of what each link should do. There are specifications
that attempt to tackle describing those details. Here is an incomplete list
that I know of:
HATEOAS: restfulapi.net/hateoas/
Siren: github.com/kevinswiber/siren
Hydra: www.hydra-cg.com/
1.7 When to use OpenAPI

Always.
I hope that statement triggered the picture of a grinning author. I couldn’t resist. But let’s take a
look at when using OpenAPI makes sense.
9
OpenAPI describes HTTP based APIs (including RESTful APIs) so when you’re tasked with
designing, managing and in some cases consuming the API, then OpenAPI makes sense. Of
course if you’re dealing with other API technologies that don’t leverage HTTP, such as gRPC or
GraphQL… then OpenAPI doesn’t make sense at all.
For this section, when we refer to APIs we’re referring to HTTP based APIs. It’s a little easier to
communicate with that assumption.
1.7.1 For API consumers

If you’re required to consume some API you may need an SDK, and if you have OpenAPI you
could generate SDKs for many different languages. The benefit is in having familiarity with a
single type of SDK or even customizing the SDK to suit your needs. Each and every API
described with OpenAPI can then be turned into an SDK of your choosing. Although typically
the SDKs provided by tools such as SwaggerCodegen or OpenapiGenerator are sufficient and
give a good head start into developing clients.
More importantly is the ability to know what to build a client against, and to even develop
against mock servers, generated by the same OpenAPI definition.
1.7.2 For API producers

Building APIs can be quite fun, particularly when you have a contract to develop against (and
you agree with that design! Perhaps a different conversation). Building out the boilerplate of an
HTTP server is less fun once you’ve done it umpteen times. Generating boilerplate code and
stubs from an OpenAPI definition gives you speed and consistency ( since you can customize the
templates to your needs ).
Although there are even more exciting methods of developing APIs, using OpenAPI definitions
during runtime to act as a router (have API operations map to classes/methods in code) and as a
validation layer (incoming requests will fail validation unless they conform to the OpenAPI
definition’s schema). Such practices are becoming more common in microservice-oriented
architecture where services are being built-out at a faster rate.
1.7.3 For API designers

Designing APIs has also been given a new focus of late ( at least at the time of writing ) and its
importance cannot be understated. While I’m a huge fan of Agile practices ( short feedback
cycles ) and the art of failing fast ( ie: bringing products to market quicker to validate
success/failure )… APIs should still be designed with longevity in mind as changing them,
means changing the consumers ( typically beyond your control ). No-one likes getting stuck
maintaining an old API!

10
OpenAPI is a medium to communicate to both consumers and producers, allowing designers to

get feedback early in the process and to iterate based on that feedback.
Design becomes even more interesting when it comes to managing more than one API. In those
cases consistency also plays an important role.
Standardizing all your APIs to have consistent patterns becomes possible when you can measure
those patterns. OpenAPI definitions is such a measurement.
1.8 This book

This book aims to help you understand how OpenAPI works, how it and the tooling can be used
to design APIs, and how you can create advanced and very specific work flows for your team
and organization.
In my opinion, all efforts in OpenAPI are aimed at automating parts of your work flow thus
freeing your team to accomplish more. The small upfront cost of describing APIs with OpenAPI
is greatly offset by the power you can wield leveraging it, and the new opportunities it presents.
This book is broken down into three parts…
Part one deals with OpenAPI literacy and introduces you to the syntax and structure of
OpenAPI definitions. Giving you the ability to describe APIs. Throughout this part we
document a contrived FarmStall API that is hosted online and is simple enough to easily
grok ( ie: understand without knowing the details ).
Part two deals in the design phase and how we’ll use the tools to create a new API and
iterate its design. We’ll be extending our contrived API into a new one.
Part three is a deep dive into some of more specific tools and work flows, including a
look at how to build your own OpenAPI tooling and features.
1.9 Part One

Part one will have the following diagram to indicate where we are in the scheme of things…

11
Figure 1.3 Where we are
We’ll progressively highlight those sections as we’re about to learn them.
Onward!
1.10 Summary
OpenAPI is a specification for describing HTTP-based APIs, most notably RESTful
APIs.
Swagger is a trademarked set of tools by SmartBear.
Describing APIs into a definition (ie: YAML file) allows you to leverage tools to help
automate a lot of API related processes.
OpenAPI is useful for consumers, producers and API designers. Each can benefit from
knowing and utilizing tools that consume OpenAPI definitions.
This book will give you further understanding and a knowledge base of how to work with
OpenAPI. To ultimately incorporate it into your team and organization work flows.

12
Getting set up to make API Requests
This chapter covers:

2
Introducing the FarmStall API and some of its business logic
Introducing a tool to make HTTP requests — Postman
Executing API requests and inspecting the responses
Our task in part one is to describe facets of an API called FarmStall.
FarmStall is an API designed specifically for this book, and was made to be as simple as
possible. For those interested, the server was written in Go and you are more than welcome to
inspect the source code at github.com/ponelat/farmstall. The API is hosted online at
farmstall.ponelat.com/v1/ (v1 is specifically for part one).
Before we can describe this API, we’ll need to understand how it works and to be able to make
HTTP requests and inspect the responses.
In this chapter we’ll be looking at how to use a tool called Postman, to make HTTP requests
against our API. We’ll be verifying that we get "decent looking" responses without concerning
ourselves too much with the details of those responses.
We also want to learn a bit about the business domain of the API so that we have an
understanding of what we’re doing. This will make it easier to describe later on.
What we’ll be touching on
Postman — getpostman.com
FarmStall API landing page — farmstall.ponelat.com/
FarmStall API — farmstall.ponelat.com/v1/reviews

13
(Source code) — github.com/ponelat/farmstall
Figure 2.1 Where we are
2.1 The problem

Our problem in this chapter is to discover and learn more about the FarmStall API. In particular
we want to interact with it and confirm some basics, such as access and the ability to create
requests and inspect the responses.
First an overview of the API itself…
SIDEBAR FarmStall API Overview

The FarmStall API is hosted on farmstall.ponelat.com/v1 The API’s primary
focus is to allow patrons of the Farmer’s Market to write up reviews and
give their feedback on their experiences. Users can submit anonymous
reviews, which include a message and a rating (1 to 5 inclusive). Users can
also sign up to create reviews that will then be associated with them. Once
signed up, they can get a "UserToken" to create reviews with their user ID.
2.1.1 First two operations of FarmStall API

The FarmStall API has several operations and we’re going to try the following two…
To get a list of public reviews you can use GET /reviews, you can filter reviews by their
rating using the query parameter maxRating.

14
To submit a new review you can use POST /reviews, the body of this request will
include message and rating fields.
Table 2.1mAPI Operations Table

Method URI Query Params Body Response
GET /reviews maxRating (1-5) N/A ?
POST /reviews N/A {message: "Was good.", rating: ?
5}
From the above information we can gather enough detailed information create our first two
requests, including where the API is hosted (farmstall.ponelat.com/v1) and the details of each
operation. You will note in the above table that the Response column has question marks, our
task in this chapter is to fill out those question marks by personally verifying what responses
come back from each operation.
So how do we make these HTTP requests? Fortunately for API folks there are numerous ways
that we can make these HTTP requests. From the brave who’d try their hand using telnet, the
practical ones who would use curl, to the individuals who have whole software suites with bells,
whistles and bunches of utilities.
NOTE For the brave

While no-one really writes HTTP requests by hand, I encourage you do so.
It is actually quite satisfying when you form an HTTP request completely
from scratch and get a response. I’ll stick a section at the end of this
chapter (not a biggie) to craft a request using the low level tools: telnet
(for HTTP) and openssl (for HTTPS). Watch out for that!
There is no hard requirement for you to use any particular tool for making HTTP requests, and
we’ve tried to structure this book in a way as to steer clear where ever possible from requiring
those tools. However I’d still encourage you to try out the suggested tools as-is, to more closely
follow along. Perhaps there are features that you can incorporate back into your own arsenal!
Without further ado lets learn about Postman.
2.2 Getting set up with Postman

Postman is a general HTTP tool that has a pleasant user interface and is suitable for beginners
and professionals alike. It can be a bit overwhelming if we look at all the text boxes, but it has
got good bones.
It was chosen as a tool for this book predominately because of its popularity (so that you’re not
stuck using an esoteric tool like some that I use) and because of the many features it provides.
Some you’ll find useful and others you might find inspirational.

15
Lets go and get it!
2.2.1 Installing Postman

In order to use Postman we need to install it. So go ahead and download then install it from
getpostman.com (or directly from www.getpostman.com/downloads/). It has support for
Microsoft Windows, macOS and most Linux distributions.
At the time of writing Postman was on version 6.7.2. Your version may look and act a little
differently depending on how much the authors of Postman change it in the interim. The UI has
been pretty stable so it should look similar to the screen-shots in this chapter.
Also, during the period when this was being written you did not need to create an account with
Postman in order to use it, although they will encourage you to do so. There are free and paid-for
plans, as well as the option to NOT create any account at all. For this chapter we’ll assume you
didn’t create an account so that we’ll only use the features that are available to non registered
users, which should be ample for our purposes.
Go ahead and install Postman, I’ll wait :)
2.3 FarmStall API

We’re going to make requests against our FarmStall API, but before we do a quick note…
The data in the FarmStall API will persist but only for a day or two, so that its doesn’t start to
overflow with too much data (its only a little service!).
It was designed specifically for this book to help guide us in describing an existing API, and it
wasn’t designed to be robust enough to handle production level data. If you add a review one day
and don’t see it the next, you’re not going crazy — the API is just cleaning up!
To get to grips with the basics of creating an HTTP request we’re going to execute two of them.
A GET request with query parameters, and a POST request with a header parameter. We’ll
progressively examine the details of these operations as we go along, for now we’re going to
focus more on the practical side of making requests and less on what the operations are actually
doing.
Lets start by getting a list of reviews from the API.
2.4 Our first request!

From the two operations described in the beginning of this chapter we’re going to start by getting
the list of reviews. It has the following details…

16
Table 2.2mGET /reviews

GET /reviews maxRating (1-5) N/A ?
From it we know that it is a GET method and that it has at least one query parameter called
maxRating. This parameter accepts a number from 1 to 5 inclusive.
Operations are often described relative to where the server is hosted and this API has a base URL
of farmstall.ponelat.com/v1 so the URL for GET /reviews becomes:
farmstall.ponelat.com/v1/reviews
If we add in the query parameter it’ll form our final URL of:
farmstall.ponelat.com/v1/reviews?maxRating=5
Armed with a URL and a method we have enough to execute this particular request — time to
use Postman.
2.4.1 Forming the request in Postman

If you haven’t done so already, go ahead and start up Postman. We want to get to the main page
so if you’re confronted by a welcome modal feel free to dismiss it. You can generally dismiss
modals by clicking on the small "x" at the top right side of the modal.
Here are the key areas in the main page that we are interested in (for our GET request):
Figure 2.2 Postman - the key areas

17
1. HTTP method drop-down This selects the method to use. The default is likely GET but
you can select it again if it isn’t already.
2. URL input box This is where we will put the URL of the endpoint we want to make the
request against.
3. Send request button The button that executes the request.
To create a request against our endpoint we need to add the URL into the URL input box and hit
the send button after that, so go ahead and type it out. You should end up with the following…
Figure 2.3 Postman - GET /reviews
After hitting send, you should see a chunk of JSON data in the Response Body section. This is
the result of us executing the request. If you see this JSON data — congratulations, you’ve
successfully executed a request!

18
Figure 2.4 Postman - GET /reviews Response
NOTE If for some reason you encountered an error in the response, that’s okay. It
could be that there is a typo, that the server is down/misbehaving or some
other unforeseen reason. If you’re happy you wrote the request correctly,
that is enough for now. We’ll have more examples later on in the chapter
that we can test against.
2.4.2 Verification
Wonderful… we should now see some response data from our request. Confirming that our API
works and that we can reach it. Our response data should look similar to the following:
Listing 2.1 Data received from GET /reviews

[
{
"message": "Was awesome.",
"rating": 5,
"uuid": "16f5e7e1-b581-4ca4-8af2-8dead5894869",
"userId": null
},
{
"message": "Was aweful",
...more of the same...
Now we can fill in the question mark in our operation table, as we know what the response data
is! Later on we’ll need to describe this data, for now we’re just satisfied that the operation works
and does indeed return some data.
Now let’s try creating a new review by executing a POST request.

19
2.5 Adding a Review to the FarmStall API

Looking at the FarmStall documentation table we can see that the operation we’re after is POST
/reviews. It takes no query parameters but it does require a body. In this case the response isn’t
the most interesting part of the operation, what is more interesting is that we are adding data into
the API.
Table 2.3mGET /reviews

POST /reviews N/A {message: "Was good.", rating: ?
5}
One of the key differences between POST and GET is the request body. One could conceivably
send data as query parameters, but they impose too many limitations. From size limitations of
query parameters, to the fact that they cannot contain binary data. A request body doesn’t have
these limitations, the size is limited only by practicality and the body can contain binary data.
NOTE Another interesting benefit of sending data in the body is security. Query
parameters are part of the URL, and as such, often get logged by servers
and proxies. If you were to send secret data as query parameters, there is
a good chance it will be recorded somewhere between your client and the
server. Whereas bodies are most often not processed by proxies, nor are
they typically logged.
In the POST /reviews operation, the body is required to be in JSON format. In this format we
can see it’s an object that has two fields.
They are message and rating.
message will be a string, and is the feedback for the Market.

rating will be a number, between 1 and 5 inclusive. Which will indicate our general
experience where 1 is the worst and 5 is the best.
Let us build the request…
Listing 2.2 JSON Request body for POST /review

{
"message": "Was pretty good.",
"rating": 4
}
As we previously did with the GET /reviews operation, we need to combine the URI with the
base URL of the server to form the following complete URL:
farmstall.ponleat.com/v1/reviews
20
Good stuff, now let’s go through what we need to do in Postman in order to execute this request.
We’ll need to do the following:
1. Change the method to be POST

2. Type out the URL to be farmstall.ponelat.com/v1/reviews (same as the GET /review)
3. Select the Body Tab, so that we can type out the body
4. Type out the JSON body that includes the message and rating fields
5. Ensure that the content type is set to JSON (or application/json). Depends on the UI
(User Interface)
Number (5) will set a special header called Content-Type which indicates to the server which
media type our data is in (more on that later). Since the UI of Postman could change, we’ll need
to double check that it is set, and we will also see that other headers can be easily added to future
requests.
First go ahead and make the changes in Postman so that you see the following (allowing for
minor differences):
Figure 2.5 Postman - POST /reviews Was Good.
Now confirm that the Content-Type header was set and that its value is application/json
(the official media type for JSON data).
There is a tab in the Postman main page specifically for headers. When you typed out your body
there was also a dropdown for selecting the content type of the data written. Postman will create
the header for us based on this value, but we need to be sure. So go ahead, click on the header tab
and ensure it looks similar to the following. Content-Type: application/json

21
Figure 2.6 Postman - POST /reviews Headers Tab
NOTE
Listing 2.3 Executing Requests
Great! Our request is ready to send. After clicking on the Send button the new review should be
created. To confirm that it was created you should see the following in the Response Body
section of Postman, as well as the Status code 201 (which is for "Resource Created" or just
"Created").
Listing 2.4 JSON response body from POST /review

{
"message": "Was pretty good.",
"rating": 4,
"uuid":"16f5e7e1-b581-4ca4-8af2-8dead5894869",
"userId": null
}
Note that this value will be different (its random)

22
Figure 2.7 Postman - POST /review Response
2.5.1 Verification
What have we accomplished so far? We’ve successfully executed two requests. One for getting
the list of reviews, and another for creating a new review. Our operations details table has now
been verified — and is telling the truth! For now, just seeing reasonable data is enough. Soon
we’re going to describe these operations in a way that clarifies what is possible, without actually
executing requests and making assumptions about the data.
Now that we’re able to make basic requests with Postman, we can have a little fun and practice
with more APIs!
2.6 Practice
Now for a bit of practice! The following HTTP requests are a short list of APIs that have fun,
interesting or perhaps even useful responses. Given the nature of the world, its entirely possible
that some (hopefully not all) of these APIs may become unavailable, or worse, change their
interfaces so that these requests will fail! The latter is something we hope to avoid when
designing our own APIs.
The ones chosen here were considered to be stable enough at time of print but we hope you
understand that they might change. We’ve put the expected results at the end of this chapter so
that you can compare with your own.
Withour further ado here are the requests…

23
2.6.1 Fun API requests to make

A little fun with cat (and other animal) facts.
Listing 2.5 Cat Facts API

Documentation: https://alexwohlbruck.github.io/cat-facts/docs/
Server: https://cat-fact.herokuapp.com
GET /facts?animal_type=cat,horse
GET /facts/random
Example response:
{
"_id": "58e008780aac31001185ed05",
"user": "58e007480aac31001185ecef",
"text": "Owning a cat can reduce the risk of stroke and heart attack by a third.",
"__v": 0,
"updatedAt": "2019-01-19T21:20:01.811Z",
"createdAt": "2018-03-29T20:20:03.844Z",
"deleted": false,
"type": "cat",
"source": "user",
"used": false
}
For those times you need a random image to put onto a website prototype.
Listing 2.6 LoremPixel API

Documentation: http://lorempixel.com/
Server: http://lorempixel.com
GET /{width}/{height}/{category}/{text}
Example: GET /400/200/sports/Dummy-Text

Example response:
<See image>
A look at DuckDuckGo’s search engine API.

24
Listing 2.7 DuckDuckGo API

Documentation: https://api.duckduckgo.com/api
Server: https://api.duckduckgo.com
GET /?q={query}&format=json&pretty=1
Example: /?q=cats&format=json&pretty=1
Example response:
{
"Abstract" : "",
"ImageWidth" : 0,
"AbstractSource" : "Wikipedia",
"meta" : {
"src_domain" : "en.wikipedia.org",
"blockgroup" : null,
"is_stackexchange" : null,
"dev_milestone" : "live",
...
<a bit too large to print>
And because the world needs more "Pirate speak", someone went and made an API for that too!
Listing 2.8 Pirate Talk API

Documentation: https://funtranslations.com/api/pirate
API: https://api.funtranslations.com
POST /translate/pirate.json?text={text}
Example:
POST /translate/pirate.json?text=Hello%20Good%20Sir
Note: %20 is URL encoding for spaces
Example response:
{
"success": {
"total": 1
},
"contents": {
"translated": "Ahoy Good matey",
"text": "Hello Good Sir",
"translation": "pirate"
}
}
2.7 HTTP For the brave

Bonus section! Only proceed if you feel brave…
As promised here is a section on how to craft an HTTP request completely from scratch. If
you’re feeling less than brave feel free to give this section a skip. You may spontaneously start
sporting a neck beard if you continue… you’ve been warned!
PS: There is a bit of low level jargon in this section.
There are two utilities you can use to open a TCP connection (a pipe you can read and write data
into) suitable for HTTP requests. The first is telnet which is available on most systems, and
Another random document with
no related content on Scribd:
Dirk’s stem huilde van onmacht en drift, maar Kees
verstond niet.
—Wat-te?.… wa’.… tè? krijschte die in strek-stand van

heel z’n lijf, tegen den zij-wand òpgeschuurd. Heet-
koortsige vloeiingen van vermoeiing voelde ie door z’n
armen trillen. Hij kòn niet meer; toch hield ie nog in
radelooze spanning vast, hoog z’n vork. Dirk
schreeuwde weer. Maar vaag hoorde Kees
stemmeklank in windstoei, zonder woorden. Nou ging
’t niet langer.—Dàn moest de vracht maar smakken.
Z’n borst blaasbalgde, z’n beenen gloeiden en trilden
méé, en in heeten schater woei de wind hem
hooifladders in de zweet-dampende tronie.
—Veùr op.… Veùr òp! krijschte Dirk, doldriftig en

zweetrood woelend met z’n armen in den gouden
hooibrand, woestnijdig dat Kees ’m niet verstond.—In
spanning die hem dreigde te doen flauwvallen hield
Kees nog òp de vracht, en vaag nu hoorde ie de
woorden van Dirk achter windgerucht, begreep ie op
voorkrat te moeten aanzwenken.—’t Was alsof ie bij
[214]’t begrijpen, nieuwen krachtstroom in zich voelde
gloeien.
Zacht weer schuurde ie z’n vork langs den berg.—De

wind joedel-doedelde weer, dat ’r slierten als
klapwiekende goudvleugelige vogels hem
omzwermden. Z’n oogen brandden en piekten,
morsten vol heet zand.—Maar voort ging Kees tot ie
Dirk èven zag bij ’t voorkrat, weggedoken in ’t hooi, die
eindelijk met wijdopen armen, z’n vork leegrukte.—
Zonnedaverend vlamblondde de wagen in al hoogeren
uitgroei, en stilpeinzend paard bleef turen in
droomgeduld, kop naar den grond, waar ’t hooi om z’n
stille pooten warrelde en walste een jolige wind-
horlepijp. De dissel, krom als ’n rooie bazuin, vuur-
gloeide tegen ’t hooigoud in, en feller blinkerde z’n hel-
koperen punt als ’n zonnige glanzige flakker in de
lucht. Op enkele hel-roode spaken zonneschramden
lichtkartels, maar heel ’t wielas-spul dofte donker-rood,
in schaduwkoel van hooikar-heupen. Hevig in blauwen
brand, straalde de hemel, boven ’t groen. En hooger,
de blonde rug van het gevaarte zwol áán in ’t
zingende licht. Dirk er in, er op, pal in ’t broeiende
hart, woelend in wankel met z’n stronkige ruigheid van
lijf onder de violet-blauwe kiel, z’n brons rooie, ramp-
angstig gemartelden kop, hoog tegen de lucht.—Als ’n
titan worstel-tastte en bouwde ie bijeen, bekookt,
begoten van zonnevuur; licht dat schroeide z’n
vleesch, groef en dreunde, sloeg en vrat in ’t hooi;
hooi dat in sprongen veerde, ònder handen- en
voetenwoel van den bronzigen titan. Z’n geel haar
leek brandend hooi en z’n strooien hoed droop zweet
af, op z’n heetrooien brons-zonnigen nek.—Telkens, in
verhitte prikkeling viel ie neer op de vork van Kees, als
ie de punt èven zag opschuren boven ’t voorkrat. Maar
plots dan weer, patste windruk ’m scheef, vloekte en
verwaggelde ie hulpeloos terug in ’t hooi, in driftgreep
z’n knuisten de oogen inwrijvend. Met heeten
windraas was hooizaadje z’n oogen ingewaaid als ’n
gloeiende vonk. ’t Brandde pal op z’n appel en z’n
morsige knuisten wroetten en woelden langs z’n
priemfel stekend oog. Het gloeide ’r als prik van heete
speldpunt. In razende pijndrift smakte ie zich neer,
probeerde [215]met nijdig gewrijf ’t zaadje er uit te
persen, dat ie ging voelen, groot, als ’n brandende bol
onder z’n oogleden.—’t Bloed gloeide ’m onder de
nagels. Hij blies, pufte en vloekte al driftiger. De zon
zengde z’n kop en door de hitte die ’m roosterde,
branderig verklefferde, dartelde en joedelfloot de wind
’n sarrig deuntje, bij vlagen, hoog en laag. Dirk dreigde
te bezwijmen van woede, pijngepriem en roosterende
ovenbenauwing. Onder hevig gewrijf wanhopend,
begon z’n oog te schreien, voelde ie ’t priem-vurig
stekige verzwemmen in traannat, alsof ie ’t zaadje in
’n hoek gedrongen had.—Hij kon weer ’n beetje kijken.
’t Brandde er wel, en vòòr zich zag ie niets anders dan
groene en rooie flakkering scheem’ren. Hij speurde
wel geen hooi, geen lucht, geen vork opsteek, maar hij
kéék toch. Na ’n poosje zag ie Kees uit ’n flakkerig-
groenigen krans òpduiken, en den Ouë verderop. Nou
maar weer voort, in worstel, tegen hitte en windsar.…
En kalmer als ie kon, bedaarder vooral! Met open
armen ving ie de hooigolven op, stond ie klein-
weggezakt, en half-lam gebeukt van vermoeiing te
puffen naar adem, in de rollen, stootte ie de
opgevangen stapels vooruit met z’n kin, z’n borst,
breed begraven in den hooi-blonden brand.—Terwijl
z’n achterlijf naar achteren woelde persten z’n
handen, zwaar driftig bijéén.
—Hee Ouë! kaik rais achteran? hoe stoàn die? Nai

Kees!.. jai nie. Staik jai moar deur!.. Hee!.. Ouë!..
Gerrit kwam aanklomperen, klos-klos, knerpend op ’t

grint. Z’n kop stond wrang van stuurschheid.—Hij
voelde zich geroosterd, hij zuchtte.. dat ie vast
hooikoorts had.. dat ie d’r niet meer tegen kòn. Met z’n
hark geschouderd, keek ie òp naar den wagen.
Tusschen z’n beenen sliertte hooi, hollend langs den
dijk.
—Hoho! daa’s ’n meroakel-wind! die sloàn je boel

òm!.. je hangt d’r hier àn dut sai heuldegoar òfer!
Dirk raasde van wagenberg, keek angstig naar Ouë’s

mond, om beter te begrijpen wat ie zei.
—Hang’k òfer?.… die pestwind! je ken dur.… f’rdomd

soo niet loaie.… daa’s gain doen.… da’ duurt d’r puur
twai [216]uur langerst.… iedere.… woàge.… en.. en..
as je dur dan nòg thuis kòmp!.. Strak en an lait.… de
boel veur de waireld.
Ouë Gerrit, met half dichtgeknepen oogen achter den

wagen, één beverige hand, als afdakje op z’n voorkop
geluikt, oploerend tegen ’t schelle zonnevuur, naar
gouden schaduwrug van gevaarte, schudde z’n
lokkenkop, dat z’n krullen flapperden en z’n zilveren
baard danste heen en weer, op z’n borst.
—Hoho! hou jai d’r moar stiekem deuse kant hee! dan
komp ’r t’ met juustighait in!
—D’r is nie te loaie, veur de tuikigste kerel nie! aas je

de wind dwars in je woàge hep! he’k ’t nie veuruit sait!
Kaik sàin doar! op ’t land.… kop van ’t poard teuge de
wind in, daa’s smeert. Moar goan d’r nou op de daike
’rais dwars stoan?.… debies! debies! is main ’n
kattebakkie.
—Nou, schreeuwde al zwakker stem van ouë Gerrit,
met angstigen kijk heel de polderlucht doorzoekend,—
hou je d’r moar goed, deuse kant uit.… vier en vaife
nie genog.… dan wâ sachies ansjouwe.… dan komp-
ie d’r wel.—
—Joa! makkelik sait.… jai stoan d’r hier nie laifendig

te f’rbrande.… da je de boel onders je almenak
wegwoait.. Main kristis! wâ da’ hooi hiet kookt!.. je
brant je achterlap d’r an! ’t stoan t’met te broeie
onders je poote.… hier Kees! hier!.. joa! ikke ken d’r
niks an doèn.… nou wair àchterop!.. ikke stoan hier
puur op de valreep! kaik d’r selfers moar.… t’met lait ie
veur de waireld! alles is hier.. wegsakt.. f’rfloekt aa’s je
loaje ken.… en je poote stoan aas in hait lood!.…
Weer schoof Kees, in arm-hoogen strek z’n vork van

voorkrat naar achter, in hevigen spierzwel en stronkige
krachtrukken van z’n lijf. Schurend en hijgend draaide
ie op achterkrat áán, naar Dirk toe, die te wachten zat.
Met opengesperden mond, strakwije lobbes-oogen,
ingebukt op z’n knieën, over z’n hooi heèn, rukte hij de
vracht naar zich toe, plompte ie neer, wijd-armig op
den brand-gouden golf, in woest gewoel en krakerigen
druisch van de rollen, waarin ie half verzoop en weer
overeind spartelde met woest armen- en beenen-
verweer.—Z’n kop gloeide en glom [217]als was ie met
boter ingesmeerd; z’n geel haar droop zweetvet af in
z’n nek, die dronkenrood zwol en branderig pijnde.
Beving van martelende, gehinderde werkdrift zat er in
z’n hoekige kaken en beving in z’n handen die persten
en duwden, rolden en smakten. Even moest ie, half
zittend, uithijgen. De wind bleef joedelen rukkerig om
z’n hoofd, stootte zwoelheete luchtkolken over ’t
wagen-gevaarte. Ingekneld en verbroeid, met armen
en beenen begraven onder ’t hooi, voelde ie ’n loome
bezwijming in ’m zakken, ’n heete koortsig-kruipende
verlamming door z’n lijf. Zoete hooigeur en
bloemdroesem stroomde méé met zwoele windvlagen,
z’n hijgenden mond in.—Zonnevuur blakerde z’n
hersens, z’n schouders, z’n rug. Hij voelde zich als
aan ’n spit gestoken, roosterend boven vlammenlik.—
Heel de gloei van fellen zomerbrand ziedde zich uit op

den gouden bergwagen. De hemel, wijd-hevig blauw,
dampte trilhitte uit. En tastend, vloekend, onrustig, en
sarrend-speelsch in de snikwarmte, joeg de wind, floot
ie z’n vlaagdeuntjes op doedelzak en spothoorns,
dartelend en grillig; blies ie als ademhaal van ’n
nijlpaard, pufte dan weer aan, kucherig en zwak, als
hoest van ’n grijsaard, schaterde plots weer òp als
wild stemmenkoor van jubelende cherubijntjes,
meesliertend heeten stroom van landgeuren uit klaver-
en groentevelden, tusschen brandenden warrel van
stof.—
Al loomer voelde Dirk bezwijming opkruipen in z’n lijf.

Z’n handen beefden, z’n oogen loken. ’n Zachte neig,
duizelig en slaperig-bedwelmend, omkronkelde ’m,
soezelde en trok ’m in ’t hooi. Hij voelde dat ie zich
moest laten smakken tusschen de brandende rollen,
in den zwijmel van snikhitte, windmartel en zwoel-
geuren rondom.—Maar weer ’n heftige windvlaag
schoot pal in z’n gezicht, frischte ’m èven òp,
vergloeide erger daarna weer z’n oogen en hals, in
blazende heete tochtvlagen.—
Zwaarder, lam-loomer waggelde ie voort op ’t
zengende hooi, strompelig en doodop.
Klein leek ’t paardje onder hooigevaarte. Stil-suf in de

hitte, stond ’t mijmerend aan ’t voorkrat, met zachten
fladder van [218]manen. Klein en weggedoken de kar,
met z’n binten en donkergroene zijwanden, in huif van
schaduw gevangen. En donkerder ’t assenrood en
wielspul duisterde onder den berg boven ’t raam en
blond gevaarte, uitgebouwd in welving, ontzaglijk
tegen luchtblauw, als ’n duin van goud, blond-gloeiend
goud, schroeiend in zonnevuur.
Kees had weer ’n zware vork opgestoken, kwam

aanzetten, en ingedrukt op ’t hooi lag Dirk’s kop, z’n
romp en beenen wèggewoeld. Als afgehouen levende
tronie op ’t brandhooi, loerde z’n zorg-gekerfd hoofd
daar, rood-bezweet en grimmig-bekommerd,
doorgroefd van ploeterangst, naar den stapel die
òppieken kwam.—Zwaar in schuur, teende Kees z’n
lijf òp, smeet ie heet de brandende golf in wrang-rooie
tronie van Dirk, die plots z’n armen uit ’t hooi opsloeg
en ademsnikkend, in blaas en puf, de rollen naar zich
toe trok. Schreeuwend achter de ingeknelde stapel
angstigde z’n stem nog:
—Kaik.… jai d’rais Kees!.. hoeke kant ikke uit mot!..

Aifig f’rvloekt aa’s ’k ’t weut.
Kees had z’n vork teruggehaald, stond zelf nog half te

duizelen van pijltjes die z’n oogen, hals, mond en
ooren ingewaaid priemden. Stom zweet-dampend en
hijgend liep ie naar achter.
—F’rfloekt! hai hangt d’r heuldegoar noar deuse kant!..
glad-en-al mis! Strak-en àn is tie d’r weust.… je mot
aêre kant houê!
Dirk schrok hevig.
—Nou.… ikke ken d’r nie sien! barstte ie uit, je stoan

d’r hier te broeie en de wind sloàn je aige blind.… die
laileke kaketoe! woar da haine mot! die gaift.… je de
hande vol! da’ kreng! da’ false loeder.
—Aa’s je nou moàr op ’t achterkrat anstuurt!
—Gaif d’r dan snóf’rjenne niks meer van veure àn!.…

aêrs trap ik doar de boel weer omkant!
In joedelenden sar bleef windruk tarten, de

zwoegbeestige kerels rammeiend. Dirk’s gezicht
spande, en angstigde al meer, bij elken nieuwen,
hoogeren aansjouw van Kees. Hij voelde den wagen
al smakken.—Kees, geen stom woord klagend, stond
[219]sterker te hijgen voor z’n hooibergjes, zich voelend
als ’n geslagen kind, òp en verlamd door windweer,
woest op ’n ding dat ie niet grijpen, niet ranselen kon
in z’n drift. Iedere inboor van z’n vork viel ’m tien maal
zwaarder dan bij ’t begin. Bij elken opzwaai zwol z’n
lichaam tot barstende kracht. Rond z’n beenen
schuifelde een warrel van leven en de zon zengde z’n
lijf, alsof ’t op ’n brandstapel vlamomlekt schroeide.
Witte hitte trilde over den polder, paarsig-ijl tegen

forthoogten, alsof de heele aardkom verteerde in één
schroei van stilwerkend wegvretend vuur. Onder den
dijk gloeiden vèraf, de hel-roode, jubel-roode stolpjes,
vlammen in luchtkobalt uitgebarsten dóór ’t porcelein-
gloeiend azuur.—Hooiwagens blondden in goudbrand
en schelven dampten witte hitte uit. Telkens, als heete
blaas-adem, vlaagde de wind òp, zwoel tegen
werkers-zweetkoppen; kittelkilde even in d’r ontbloote
klefferige halzen. Hun kleeren schroeiden ze op ’t lijf.
Hun handen en polsen gloeiden, oogen en hersens
doften. In den ban van hun martelzwoeg, tusschen
wind en snikhitte, ging één stille onuitgesproken
begeerte naar koel nat, ’n snak naar ademhaal, ’n
verlangen naar rust in schaduw-gras, om èven maar
lenden te rekken, lijf te woelen in luien genotstroom
van leven. Zacht beslopen voelden ze zich in loomen
zwijmel. En sterker blakerde zon, plakte en zoog hun
goed vast aan de brandrige leden.—Kees, ongewoon
te hooien, voelde al warmere koortsrilling in z’n
polsen, en jeuk in ’t bloed. Z’n gemartelde keel snakte
naar kou.—Dorst droogde heet en jeukerig z’n
gehemelte uit.—Z’n mond stond dor, in droge
branderigheid. Dorst vampyrde op de warme stik-
benauwde werkers-strotten, als ’n dier dat tergde, hun
keel in brand kon zetten; ze martelden tot ze vloekten
en raasden van gift en onmacht tegen de zon, die
blakerfel, z’n àl witter vuur neergloeide op hun
koppen; de zon, de groote, geweldige schroeier, die
hun oogen doorpriemde en hun half-naakte, zweet
dampende zwoeglijven zengde, vermartelde zonder
genade.—
Zoo, onder worstel tegen wind, die de mannen

grommen deed [220]en huil-vloeken, groeide de wagen
hooger òp, als ’n berg, ontzaglijk van goud-hel geweld
in de peillooze luchtzee, eindloos gloeiend blauw, en
de hooge woel van Dirk op de kar daar, tègen ’t
hemelhelle licht in. Al langzamer, in waggelgang kroop
en worstelde ie z’n lijf door ’t hooi, telkens met z’n kin
op ’t brandende gegolf, z’n armen verspartelend in de
rollen. Achter elkaar, holderdebolder, in sliertenden
kringdans en grissenden zwier, fladderden hooihalmen
de lucht in, over dijk en wei. Verder op, Ouë Gerrit
strompelde nà, wàt ie vatten kon, met z’n hark.—
—F’rdomme, wa’ da’ hooi brant.… aa’s ’n vlam.

Debies! schreeuwde Dirk naar beneden van ’t
geweldige gevaarte, blauw verwapperend z’n kiel op ’t
goud. De kin ingeperst op ’t hooi, zag Kees alleen
Dirk’s kop, angstig-wachtend op nieuwe vork.
—Hoeveul.… hai je d’r nog Kees!
—Nog ’n vaif vorke, galmde ie terug, met z’n rug naar

Dirk gekeerd. Bevend van zwaarte had ie z’n vork
òpgezwierd, en ruk-hevig boven z’n kop gesmakt. Als
loerde de wind plots naar z’n zwaai, zòò joedelde hij
op Kees àf, plukte heele bossen uit z’n vork weg, en
regende woeste gouden warrelpijlen om z’n zweet-
tronie en lijf.
—Effe hooger je vork Kees! ikke kèn d’r soo nie bai!
Kees waggelde voort, in den brandenden fladder en

sliert van hooi. Z’n adem snikte, brak àf in de keel.…
Hij voelde weer dat ie niet hooger kòn. En Dirk zat te
vèr, durfde niet trappen, uit angst dat de boel zou
inzinken. Verlegen, klokkerde ie ’n slok in uit z’n
veldflesch, die gekookt gloeide op ’t hooi, en loerde,
wachtte. ’n Minuut in worstel tegen wind, bleef Kees
staan op z’n teenen, blindgegooid van licht en
hooistrooisel, vloekend rauw, uitzinnig van drift, dat
Dirk niet greep. Maar die wachtte tot Kees hóóger op
zou steken. Woest, in fladder zag ie hooi verslierten
zonder dat de vork naar ’m toeschoof. Dirk bòven
vloekte bezeten, Kees beneden, stond te gloeien van
gift, adem-òp, dat Dirk niet vast greep.—Z’n kop stikte
in hooipijlen en stofdotten; z’n ooren, haar en oogen
werden [221]volgestort van brandend gefladder.
Brullend schreeuwde Kees:
—Nou Dirrèk!.… hep je sain nie an achterkràt?!
—Vàst nie! kom d’r hier op sai, f’rdomd aa’sk sain

hoale ken.… die glad.. joànes.. van ’n wind.
Hij had geprobeerd Dirk, maar waggel-zwaar was ie

achterover gesmakt, z’n kop pal in den fellen zongloei.
Nou kon ie geen woord meer zeggen. Zacht schoof
Kees òm, van achterkrat naar zijhoek. Windgesar floot
om ’m heen, raasde z’n oogen blind, z’n kop duizelig
van hevige inspanning en martel. Woester
schreeuwden ze tegen elkaar; cyklopischer in
weerstand en krachtzwel van spieren en lijf
aangespannen. En toch was ’r ’n angstig elkaar
zoeken te begrijpen met één woord, ’n schreeuw van
rauwen vloek, gegooid boven op ’n woedekreet van
wanhoop en vergeefschen ploeter.
Ouë Gerrit had ’t afgewaaide te hoop geharkt en

vastgeboord aan z’n vork. Stil, puffend in ademhijg
loerde ie schuwtjes òp naar den wagen.
—Hoho! da’ pakt skaif uit, pakt skaif uit.… aa’s die d’r
goed-enne-wel an de dorsch komp hiet ikke-en-gain
Gerrit meer!
Dirk raasde wat van den bergwagen af naar den Ouë.
—De leste vork goan d’r alewel òp.… en dan sel ’t

pondere sain.… hoe stoan die?
—Nou t’met heuldegoar f’rsakt op de windsai! hu!

hu!… kraaide de Ouë schel-scherp terug, handdakje
beverig voor z’n oogen gekneld.—
—Leste vork en dan pondere alewel!
Hijgzuchtend woelde Dirk op den berg, in laatsten

rolslag. Wind floot snelleren joedel en spotte uit blauw
luchtewelf, in sliert en slag, flap en dans.
—F’rdomd aa’s ’k ooit soo loaie hep! schreeuwde Dirk,

’t hooi is d’r wild aa’s ’n knain.… ’t springt d’r onders je
poote wèg. Hee, Kees!.… wa doèn jai?.… sloap ie?.…
hooikoors?.…
Kees was op den dijk tegen de laatste hooischelf

ingezakt, met z’n brandenden rug op ’t gloeibergje. Hij
voelde koortsvloeiing in z’n bloed, ’n matte doffe
gloeiing in z’n handen, ’n [222]piekenden brand van
prikjes in z’n polsen. Z’n oogen holden verschroeid in
z’n kop.
Nou moest ie, al was ’t maar tien minuutjes even

uitblazen, met oogen toch star open, want anders,
voelde ie stellig, zou hem slaap bekruipen, matte,
paffe luier en zwijm..—
Hoog en geweldig uitgebouwd reuzigde de wagen als
goud duin-gevaarte tegen ’t brand-blauw van den
hemel, peilloos trillend van hellen zonneblaker; licht,
dat in heeten windwarrel langs weien en bouwgrond
één kleurbeving goot, brio van heete glansen,
zomerhel en zònnegloeiend over riet, koorn en
groenten vertrilde.—Dirk zat op z’n knieën in ’t hooi te
puffen, wachtend op Kees, blij dat ie ook even kon
uitademen. En strak in stommen staar, keek ie hoog
van z’n goudberg eindloos polderland over.—
Zijïg-zachte warmglanzende goudgolving moireerde

door ’t hooi-zwad, en de nog groen-blauwe
koornhalmen ruischten en zuchtten als orgelregisters
waar lucht-ziel in áánvloeit. Trillend gloeiende lucht,
laaiend blink-goud van zonnigen zomerbrand vrat in
op dakjes, karrenrood en groen, en witte wasemhette
nevelde neer, tusschen gloei-gouden schelven en
schoovensleur van karwei-hokkers. Windwiegel
verstoof gouddamp bij iederen stap der landwerkers.
In de heet-zonnige lucht, boven eindloos-vlammend

goudgroen van weiland, zoemden en klank-snorden
goud-vliegjes en wespen. Boven de donker-
groenende klavervelden, die dampten in gouden hitte,
spartelde ’t in de geurende zonnelucht van àl diertjes.
Hommels in d’r kleurig fluweel schommelden en
gonsden en verzongen met hun tril-vleugeltjes,
zomerlied van honinghaal; plots wègzwaaiend op
windstoot uit hun vaart-vlucht naar de wei-bloemen.
Wespjes in d’r spitsige pracht, zwevend en trillend op
één plek, in hun goudvleugelige vlucht bepoeierd met
zonnestof, zwierven hoog en laag in kransjes van licht.
Gewemel en gezoem overal,—tusschen purper
smeulende en hel-paarse klaver en gras,—van
gloeiende torretjes, in fonkelgoud en weerlicht-blauw,
vol gloedjes en glansjes dooreenzwermend; kevertjes
rood, in zonnegloor, als heete lak-vlammige
[223]kruipertjes, rondstoeiend om spinnewebben, die
als lichtend rag zij-ïg elektriseerden en vonkten in den
zonnedag.
In geurenzwijmel dronken, volgesapt van zoeten

honing, slingerden de hommels door ’t luchtblauw, en
de klavervelden in den rose-witten en rooden
bloemengloei, knapperden van licht. Op dwarspaadjes
en dijken in wilden wriemel van madelief en
boterbloemen, die dropen van glans, rookte ’t walstroo
rond, gelige trosjes, uitademend zaligen zomergeur,
diep bedwelmend; zoeten geur van zonnegrond, als
vijgenreuk rondrookend heel den polder door, in
gelukaangeurenden juich van levenslust. ’t Heete gras
gloeide, hoog prachtgroen, heet goud-groen in hellen
glinster, rag en lichtend in ’t weidevuur.
De polderplasjes wemelden van leven, zogen

hemelblauw in, warmdonker terugspiegelend op ’t
watervlak, en tusschen het ruischriet, snerpte gors,
zongen er schelle vogelkeeltjes òp, van kievit en
spreeuwen, floot lokkend-klaar eenzame wielewaal.
Zonnige schitter plaste op de watertjes, die dampig en
fonkelspattend, kronkelig en zonnewiegelend,
tusschen ’t glanshelle weigroen slingerden.
Koeiendrom op ’t malsch gesapte weiland, waar et-
groen laag gloeide, glansde en blankte, in git en wit, in
rood en blond, grazend doom’rig en traag-rustig op ’t
afgemaaide gras, dat sapte en bruiste van gloed-licht.
—Soms plots in draf, holde ’t vee langs sloot-greppel,
spròng zot en onbeholpen terug in dwaze gebaren.
Soms, op lui-bijééngegroepte koeien, zonnebroeiend,
zakte parmantig ’n spreeuwpaar, stappend op hun
ruggen als zwart-glanzende wandelaartjes, happend
vliegen, die om neus en oogen van de koeien sarden,
in kwellenden kringetjesgons.—Paardjes en veulens,
roodglanzend, schimmelhitjes, grijzigblank, holden
door ’t zomergroen, in slanke vlucht van manen en
staart. En telkens van de dammen, waggelden òp de
hooiwagens, hoog tegen trillend azuur, hel-blond,
goudgeel met den woel der blauw-bekielde kerels er
òp, als uitgesmeed tegen ’t hemel-ontzaglijke; de
wagens achter elkaar in krakenden hort, in piependen
kreun en zuchtenden steun, den bestráten polderweg
àf, plots wiel-ratelend, omkolkt van zandhoos. En
hoog in de lucht, dwars [224]door donkeren klapwiek
van kraaien waaierde blanke vlucht van leeuwrik, z’n
zilver gerucht verjubelend door zonneruimte.
Overal zomervuur drupte brandende bloem-boeketten

van zengend goud op ’t heete gras.
Heel de polder lag droomrig stil in den zonneblaker te

roosteren. Alleen van den blinkenden bekeiden
hoofdweg warrelde stof òp bij windrukken, in zwier en
hoos, van damp en licht. Tusschen ’t gras brandde ’t
bloemgezwerm, geel en blank, rood en brons, en hel-
vlammige klaprozen bij dijken, slankten uit boven ’t
groen, in fel kalkoenerood. Zomerhitte snikkend lag te
zwijmelen tusschen karwijschooven en hooi. Broei-
wind goot wilde striemsels van kleurbeving over ’t
land, telkens anders verglijend van glans. En de
oneindige polderkom, lag als ’n luidlooze wereld van
stil gebeuren, brandend en murmelend, zangerig
wind-doedelend en doorplechtigd van ruischende
stilte-muziek der weien,—matelooze graszee en
luchtewelf.—
Op dijken, achter stolpjes, sjokkerden soms kindertjes

áán, roodharige en blonde jochies, speelsch zwierend
vóór boerderijtjes, omblakerd van zonnegloei. En
soms doken òp, uit erfjes, zoo van vèr, meisjes
roodrokkig, heel van vèr, als dribbelende
kersenmandjes in zon, vol bloeiend rood en fleurigen
schater van kleur. Inéén doken ze weg achter
kippenloop of stolp, en stil-leeg dan weer stonden de
dijken heet te trillen, groen, tegen ’t hemellicht;
verdwenen al meer schelven op de wagens,
vervlakkend ’t land uit z’n bergjes-onrust. En
rondomme, uit luchtvuur en gras, vlindergestoei
zwermde áán, witjes met blanke zeiltjes doorzond, in
argeloozen klapwiek van vleugeltjes, boven klaver en
walstroo, distels en riet. Ze fladderzwierden zeilend
door den blaker-gouden, wit-gouden dag. Goudvosjes
en dagpauwoogen in glans brandend, verterend in
eigen gloed, zwermden mee, méé in zomerzwijm,
dronken en half-verstikt al in zoete walm van
bloemengeur waarin ze vlerkten.
Dirk zat nog gehurkt uit te rusten op z’n kar, in

slaapsuffen dommel. [225]
Ouë Gerrit, stug en chagrijnigend over iets dat ie niet

zeggen wou, harkte weer bij aan den overhellenden
wagenkant. Met z’n handen rukte ie zware dotten
langs de wielen af, gooide ze neer op den dijk, waar
ze ritselden en zacht kropen om z’n voeten, tot ze
plots, met ’n fellen windflap mee de lucht instoeiden,
heel vèr.
Kees was uit z’n koortsige loomheid en dommel wat

opgefrischt. Dirk had ie ’t achterbindtouw opgegooid,
die in angstigen hurkkruip op ’t hellende gevaarte bij
voorkrat ’n knoop sloeg. In ’n zwiep sliertte hij ’t touw
weer naar beneden, om te sjorren. Met één been
tegen achterkrat aangeperst, z’n voet in ’t gloeihooi
wroetend, heesch Kees zich òp tegen ’t touw en
sjorde den ponder. Plots schreeuwde Dirk kort:
—Hohai! feurbint is uit de kaip!
Dirk nijdig en vloekend met wrangen kop, woelde weer

langs den ponder òp naar ’t voorkrat en haakte
bindtouw in de pondergleuf.
—Arrait! schreeuwde ie driftig.
Kees, weer met één voet in ’t hooi gestampt om zich

af te zetten van den grond, begon opnieuw met twee
handen in herkuulrukken te sjorren, maar weer van de
hoogte klonk wanhoopstem van Dirk.
—Hohai! feurbint is uit de kaip! f’rfloekte gladjanes!
Woest was ie weer naar voorkrat gekropen, duizend

maal „debies”! razend, met z’n vuist ’t brandende hooi
inwoelend, òp van ongeduld en voortvretende drift.
Weer had ie ’t touw ingeduwd!
—Hoal an!
Kees sjorde weer. Dirk, op den berg, keek in grimmige

spanning. ’t Gevaarte kraakte, kromp en steunde
onder de rukken van Kees, geholpen nog ’n beverig
handje, door Ouë Gerrit.
—Hoal an! hai hou dur! hoàl.…
Bons! ’n ruk-scheur door Kees’ arm, en weer was ’t

touw uit de pondergleuf geschoten.
—Hohai! d’ruit! da’ laileke kreng! die pestneger!

krijschte stikkend van drift Dirk weer. [226]
Dirk, in zwoeg, bloedrood nu van zorg, angst en

nijdigheid stond overeind op den wagen, stapte
staande naar ’t voorkrat.
—F’rek aa’s ’k dâ snap! dàn is de feurbint te kort.…

debies! hai ken d’r nooit nie komme soodurwais! jai
mot d’r van achtert te vèr of’rhoàle.…. dan spant hài
d’r hier te veul.… van feure.… enne springt d’ruit.… de
boel lait.… te wàit hier.… dâ hai je dur nou van mit die
staive wind! f’rvloekt.. alle duufels!.… da’ hooi brant je
je laif àf.…
In wanhoop greep Dirk z’n hoed en smakte ’m op den

dijk, dat de zon nu z’n naakten gelen kop omkookte.—
Rauw-driftig geschreeuw klonk er òp en weer, van en

naar den wagen, de stemmen verwaaid in
windgerucht.
—Ken ie van ònders nog rekke.. schreeuwde Dirk.…
hai lait.. weer..! Nou Kees.. Ouë!.. sachies àn! hoal!!
Weer sjorden de kerels achter ’t krat, in dampenden

lijfzwoeg, borsten blaasbalgend in hijg. Weer zakte
gevaarte zoetjes, daalde Dirk méé, angstig, gejaagd,
z’n zweetrooie tronie gekeerd naar den ponderkeep.
Maar weer bij sterke spanning schoot ’t touw uit,
stopten de kerels, en rees in zuchtenden ademhaal,
de hooiberg weer òp.—Dirk z’n kop bloot, woest, half
dol van wanhoop, vloekte als ’n gek, bulderde keek òp
naar de zon die z’n oogen blindsloeg van licht, stond
half te stikken van onmacht.—
—Ik bin kepot, kepot! kreunde Dirk met gesmoorde

stikkende en stervende stem.—
—Aa’s je d’rais ’n stuk touw knaipt an ’t feurbint,

schreeuwde zwakkelijk Ouë Gerrit, de kaip is d’r.…
afslaite.… hu! hu!
—F’rdomd.… daa’s net! gromde Dirk even òplevend

uit z’n stervende moeheid.—Hee Kees hier!.. bai ’t
feurkrat sit d’r ’n dot touw,.. kaik jài d’r us!
Maar Kees vloekte en wreef, in pijnkramp van z’n lijf,

z’n oogen uit.
—Steek de moord, da’ goan main ’t zweet de lampies

in! snof’rjenne wa’ bait dâ!
Als was z’n oog met ’n zuur gif volgedrupt zoo vrat en
brandde [227]’t kopzweet hem ’t oogenwit in.—Rood
geflakker vlamde ’r voòr ’m. Toch strompelde ie, half
blind naar ’t voorkrat, met Ouë Gerrit achter ’m aan.
Uit ’n hoek grabbelde Kees ’n end touw op. Met
nijdigen ruk sjorde ie ’t voorbint los en kronkelknoopte
’r ’n stuk aan vast. Op één oog voelde ie zich blind, en
pijn schroeide er in, als was ’t z’n kop uitgerukt. Toch
vond ie ’t malligheid te jammeren.
—Kloar!
Dirk op den wagen, trok áán, probeerde of ’t touw lang

genoeg was, niet meer uit de gleuf kòn.
—Te lang, slappies! knoop d’r ’n halfe slag bai! sóó,

nou! nou goan die d’r wel! snó’f’rjenne.… aa’s da
loeder d’r nou nie in blaift.… sprink sain vast op s’n
strot!
Met ’n zware poef smakte Dirk zich neer op den

ponder bij ’t katrol.
Kees en Ouë Gerrit aan achterkant, sjorden, rukten en

strak-knarsend en kreunerig bleef ’t touw kermen in de
gleuf.
—Hoal d’ran manne! hoal d’ran!
Zwaarder perste Dirk z’n lijf op den ponder, z’n

beenen spartelend in ’t hooi, z’n armen krampachtig
om den balk geklemd. Heviger sjorde Kees, dat de
wagen wiegelde, kreunde en kraak-zuchtte en ’t
gouden licht op den hooibrand meezwiepte, op-en
neer, in ’t hemelblauw.
Langzaam zakte Dirk langs pondertouw àf, dat Kees

door ’t katrol geheschen had. Met hun drieën nu

Full Chapter Designing Apis With Swagger and Openapi Meap V04 Joshua S Ponelat Lukas L Rosenstock PDF

Uploaded by

Copyright:

Available Formats

You might also like

Full Chapter Designing Apis With Swagger and Openapi Meap V04 Joshua S Ponelat Lukas L Rosenstock PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Full Chapter Designing Apis With Swagger and Openapi Meap V04 Joshua S Ponelat Lukas L Rosenstock PDF

Uploaded by

Copyright:

Available Formats

Designing APIs with Swagger and

OpenAPI MEAP V04 Joshua S Ponelat

Five Lines of Code MEAP V04 Christian Clausen

Apache Pulsar in Action MEAP V04 David Kjerrumgaard

Spring in Action - Sixth Edition (MEAP V04) Craig Walls

Domain Specific Languages Made Easy MEAP V04 Meinte

Microservices in NET Core Second Edition MEAP V04

Designing Web APIs Building APIs That Developers Love

Shut Up and Run How to Get Up Lace Up and Sweat with

Management Control with Integrated Planning Models and

Copyright 2020 Manning Publications

For more information on this and other Manning titles go to

©Manning Publications Co. To comment go to liveBook

©Manning Publications Co. To comment go to liveBook

©Manning Publications Co. To comment go to liveBook

This chapter covers:

Lets get started…​

1.1 What is an API Ecosystem?

©Manning Publications Co. To comment go to liveBook

1.2 Describing things

Let’s take a look at this story, for example.

1.2.1 Bridget’s Task

©Manning Publications Co. To comment go to liveBook

1.2.2 The potential of Bridget’s solution

1.3 What is OpenAPI?

1.3.1 Example OpenAPI Definition

Listing 1.1 Example OpenAPI Document/Definition

The API is hosted at dog.ceo/api

Where the breedName in the URI, is a string

Figure 1.1 SwaggerUI with Dogs API

1.4 Where do OpenAPI definitions fit in ?

©Manning Publications Co. To comment go to liveBook

Figure 1.2 OpenAPI

Other work flows could include…​

Automating parts of testing (APIs)

©Manning Publications Co. To comment go to liveBook

1.5 And what is Swagger?

1.6 What about REST?

NOTE A quick note regarding Hypermedia.

1.7 When to use OpenAPI

1.7.1 For API consumers

1.7.2 For API producers

1.7.3 For API designers

©Manning Publications Co. To comment go to liveBook

OpenAPI is a medium to communicate to both consumers and producers, allowing designers to

1.8 This book

This book is broken down into three parts…​

1.9 Part One

©Manning Publications Co. To comment go to liveBook

Figure 1.3 Where we are

We’ll progressively highlight those sections as we’re about to learn them.

©Manning Publications Co. To comment go to liveBook

Getting set up to make API Requests

This chapter covers:

Our task in part one is to describe facets of an API called FarmStall.

What we’ll be touching on

©Manning Publications Co. To comment go to liveBook

(Source code) — github.com/ponelat/farmstall

Lets get started…

Other work flows could include…

This book is broken down into three parts…

First an overview of the API itself…

Let us build the request…

Withour further ado here are the requests…