REST API Design: Maintaining an API Style Guide

In a microservices architecture it is important to independently develop, run and deploy microservices.
However, it is beneficial for the services to be similar enough so that working on many services is seamless for developers.
That means similar deployment strategies, development frameworks and so on. This is why Starter Kits are so useful.
A common approach also makes work across teams much smoother.

An API style guide helps another dimension of this: API design consistency.

For example, suppose have a client library function which depends on a date field. It is much more re-usable across the company if we know all microservices should expose date fields in Unix epoch time with milliseconds or another standard format. When a new microservice is being integrated, we can quickly re-use this function with a new date field without having to figure our or potentially parse a new date format just for this service.

Of course, generally an API should follow good REST principles like well-defined resources and sub-resources, but the more we get into details the more can be spelled out and adopted as convention. Just how far REST principles themselves are taken can be an organization-wide convention.
Further, many details are independent of REST and fully up to the designer; this is where consistency across an organization really helps.

The API Style Guide could be a document on the internal API Developer Portal or other API hub, or simply a wiki or Confluence document.

The following elements are useful to document in an API Style Guide. This is not an exhaustive list.

Resource Naming

For example: use plurals with camel-case or plurals with dashes (e.g. /myResources or /my-resources)

Identifier Format

Example: Use UUID for all IDs or simply integers.
Include canonical IDs for all returned resources under the field “id”.

Date Formats

Example: Use Unix epoch time with milliseconds (or without milliseconds).

Date Field Naming and Human-Readable Versions

For example, always use the convention: “createdAt”, “modifiedAt”.
If these are in Epoch time, a human readable version could be “createdAtPretty”.
See this post for more details.

Slug Fields

Example: always provide a slug name or identifier for items.
See this post for more details.

Header Conventions

E.g.: Use headers named ‘Custom-Header’ or ‘X-Custom-Header’ (although this style is technically deprecated).

Content-type Headers

Always return the proper content-type header like “application/json”.

Controlling Response Format and Language

For example, use the Accept header to request specific data formats like JSON or XML. Another example: use the Accept-Language header to request responses in different languages like English and French.

Conventions for Descriptive Metadata for Lists

The style in which metadata about lists is returned along with list results is a key design decision.
Suppose for our resource /items we also want to know the number of items returned.

We can use a custom header:

Element-Count: 5

Or we can return a top level object and return the items as a field:

  "itemCount": 5,
  "items": [ ... ]

Such a design decision is very difficult to change once clients depend on the API and start requiring data about the list itself.
We can avoid API versioning and inconsistency by adopting a standard approach in a style guide across the company.

Documentation Approach

We can have a convention on documentation. For example, all services should expose documentation on /docs as OpenAPI (Swagger).

HTTP Status Codes

These should be consistent across most APIs, but we can write down some conventions. For example: a successful update request to a resource should respond with 204 No Content and no body.

Error Response Format

For example, all errors must be in a standard format like the sample below, including a documentation link:

  "code": "123",
  "message": "Error message",
  "link": "https://documentation-link"

Hypermedia Element Conventions

If services use any hypermedia elements, these could be standardized in the style guide.
For example, for linking to related resources we could specify using HAL links.

Again, this is definitely not an exhaustive list. Any aspect of microservice API design can be written down as a convention in an API Style Guide, making such a guide an asset for Developer Experience both for API developers as well as API consumers.


Create a MySQL Docker Container with a Predefined Database

It is often useful to start up a Docker container running a database server with a pre-defined, ready and prepopulated database via an SQL script, usable as soon as the container starts.

This can be a dependency for local development, a dependency for tests, among others.

For macOS: if it is not present, install MySQL with Homebrew to get the MySQL client.

brew install mysql

To define the container we need two files in the same directory. The Dockerfile extending mysql and specifying the start script:


FROM mysql

COPY ./create-local-db.sql /tmp

CMD [ "mysqld", "--init-file=/tmp/create-local-db.sql" ]

The SQL script to define the database in the container:


-- Local database definition.



USE local_db;


  id int(10) NOT NULL,
  title varchar(30) NOT NULL DEFAULT '',

INSERT INTO books VALUES(1, 'Book 1');
INSERT INTO books VALUES(2, 'Book 2');

Build the container in the directory with Dockerfile, tagging it with the name my_db (for example):

docker build -t my_db .

Run the container on port 3306:

docker run -e MYSQL_ROOT_PASSWORD=pw -p 3306:3306 my_db

Note that we must pass the root password environment variable to the server.
(For docker-compose this would go under environment: )

The server should indicate that it is ready for connections.

In another terminal, connect to the server with MySQL client:

mysql --host= --port=3306 -u root -p

You should see the MySQL prompt and be able to run queries.

mysql> use local_db;
Database changed

mysql> show tables;
| Tables_in_local_db |
| books |
1 row in set (0.00 sec)

The MySQL database inside the Docker container is ready to use.

Generate a Diagram for a Keras Model on macOS

We can output a visualization of a Keras deep learning model using the plot_model utility function.

First the dependencies need to be installed:

$ pip install pydot
$ pip install pydotplus
$ pip install graphviz

We also need the graphviz binary:

$ sudo port install graphviz

It is also possible to use Brew (brew install graphviz).

This example code outputs a model diagram:

from keras import layers
from keras import models
from keras.utils import plot_model

network = models.Sequential()

network.add(layers.Dense(512, activation='relu', input_shape=(28*28,)))
network.add(layers.Dense(10, activation='softmax'))


This will generate the model plot in a PNG file named model.png by default.

View the result diagram image:

$ open model.png

Result image:


We can also specify a different file name in the call:

plot_model(network, to_file='my-model.png')

To also include layer shapes in the plot, omitted by default:

plot_model(network, show_shapes=True)

Capture Webcam Images with Python and OpenCV

The following code shows how to read a video frame from the webcam.

This assumes the OpenCV library for computer vision is installed. See the post on Installing OpenCV on macOS if needed.

To capture one image:

import cv2
import matplotlib.pyplot as pyplot

captureObject = cv2.VideoCapture(0)

success, testImage =

# See image numeric values.

# Plot image.
pyplot.imshow(testImage, cmap='gray')

To capture many images continuously, we just need to call read() in a loop.


Install OpenCV for Python on macOS

To install the OpenCV library for computer vision on macOS, first install the required prerequisites, then the package itself.

pip install scikit-build

pip install cmake

pip install opencv-python

Test the installation:


>> import cv2

The import should work without errors.


Export a Table or Query Result to a CSV File from Postgres

To export data from a table T (or any result of a query) in a PostgreSQL database use the following command:

$ psql -h localhost
       -U database_usr
       -d database_name
       -c "COPY (SELECT * FROM T) 
           TO '/path/file.csv' 
           DELIMITER ',' CSV HEADER;"


  • The query should be on one line; it is split here for readability.
  • Make sure you have the correct permissions to write to the directory referenced. The command may need to be run with sudo.


Simulate any HTTP Status Code from a URL for Testing

Testing code which calls APIs often involves handling various HTTP status codes from an endpoint.
When calling an external service, it may be difficult to trigger specific HTTP status codes for errors to test out code paths triggered only by those status codes being returned.
We can call the service with the desired response code in the URL path to get any arbitrary HTTP status code returned.

For example, using cURL:

$ curl -v

The result is:

> GET /503 HTTP/1.1
> Host:
> User-Agent: curl/7.54.0
> Accept: */*
< HTTP/1.1 503 Service Unavailable

Less common success status codes can be simulated as well:

$ curl -v


> GET /204 HTTP/1.1
> Host:
> User-Agent: curl/7.54.0
> Accept: */*
< HTTP/1.1 204 No Content

In a config file, we can use URLs instead of our actual dependencies to trigger error cases for tests.

See the full feature list of the HTTP Status service:

REST API Design: Transitive Inclusion, or Inlining Associated Objects

Transitive Inclusion (Transclusion for short) is a feature of REST APIs useful for clients wishing to get more than just the resource in the URL path, in one request.
We use a query string parameter called inline, or perhaps include, equal to the name of the associated objects to include.

For example, suppose that in a Books API, author objects have associated books.
A request for an author:

GET /authors/12345
  "id": 12345,
  "name": "Ralph Ellison"

The list of books associated with the author:

GET /authors/12345/books
    "id": 1,
    "title": "Invisible Man"
    "id": 2,
    "title": "Juneteenth"

We can pass the inline parameter on an author request:

GET /authors/12345?inline=books
  "id": 12345,
  "name": "Ralph Ellison",
  "books": [
      "id": 1,
      "title": "Invisible Man"
      "id": 2,
      "title": "Juneteenth"

Note the extra field “books” is included or inlined in the author object.
This way a client app can get the author object and associated books in one request, reducing round-trips. Of course if the objects are small, including the associated objects by default is the best option; this is mostly useful for large, expensive-to-retrieve associated objects.

The transitive inclusion feature can be even more powerful if we get a list of all authors in the API, inlining all of their associated books:

GET /authors?inline=books

Or we can include many associated objects:

GET /authors?include=books,articles

The result is a comprehensive list object, all in one request:

    "id": 12345,
    "name": "Ralph Ellison",
    "books": [
        "id": 1,
        "title": "Invisible Man"
        "id": 2,
        "title": "Juneteenth"
    "articles": [ ... ]
    "id": 67890,
    "name": "Doris Lessing",
    "books": [
        "id": 10,
        "title": "The Golden Notebook"
        "id": 11,
        "title": "The Fifth Child"
    "articles": [ ... ]

Such a comprehensive response object can be convenient for an app to build a page listing authors and books, for example; only a single HTTP request can be used .
Note that if the set is large, pagination can be used in addition.


Base64 Encode and Decode in Node.js

Using Node on the server side, we find that we cannot use the JavaScript functions atob and btoa. They are not defined; we get the following errors:

ReferenceError: btoa is not defined
ReferenceError: atob is not defined

The functions are defined in JavaScript in the browser, but not in server-side Node.js.

To encode to base-64, instead of btoa use the following:

const myString = 'hello'
const encoded = Buffer.from(myString)



To decode from base-64, instead of atob use the following:

const base64String = 'aGVsbG8='
const decoded = Buffer.from(base64String, 'base64')




Mock Only a Single Function from a Module with Jest

Recall that using jest.mock(module) mocks every function exported from the module.

But sometimes we need to mock only one or some functions in a module, leaving the others’ real implementations as-is.

Suppose we are using the following module of functions:


const f = () => 'Return from f'
const g = () => 'Return from g'
const h = () => 'Return from h'

module.exports = {

The code below uses a Jest spy with a mock implementation to mock out just one function while leaving alone the original implementations of the other two.


const functions = require('./my-functions')

describe('mock only one function from module', () => {
  it('should return only one mocked result', () => {
    jest.spyOn(functions, 'g')
      .mockImplementation(() => '_mock_')


    expect(functions.f()).toEqual('Return from f')
    expect(functions.h()).toEqual('Return from h')

Running the tests:

$ jest my-functions.test.js
PASS ./my-functions.test.js
mock only one function from module
✓ should return only one mocked result (14ms)

console.log my-functions.test.js:8
Return from f

console.log my-functions.test.js:9

console.log my-functions.test.js:10
Return from h

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 0.956s
Ran all test suites matching /my-functions.test.js/i.

Note that only g() returns a mocked string.