Whilst trying to solve problems, I often need to use others projects as a benchmark. But how do I represent this when writing a blog post? My answer is to write a “Hello world” RESTful API that will allow me to break everything down into chunks.
In a series of blog posts I will be:
- Designing RESTful API
- Building an API with dummy data
- Deploying the API
I will continue to cover new technologies and opinions using this dummy API a benchmark.
I won’t be getting too far into my decisions, fundamentally I will be building an abstract interface using the tools that I am familiar with. The purpose of my blog is to later challenge these ideas.
What’s the plan?
The objective of this post is to have an understanding of how the API will work.
Short term, I’ll be creating a theoretical minimum viable product of a RESTful API. It will be purposely (slightly) flawed, because flaws are interesting.
I’ll start with something everybody is familiar with – albums, artists and tracks. I’ll use albums to design a vertical prototype to save some time and set a benchmark of how the API will be structured further down the line.
Long term, I’d like to eventually reverse engineer something like Spotify, because it’s something I’m familiar with, relatable, and I’m sure building something along those lines will allow me to go over a lot of fun topics
Technical decision: Using OpenAPI
I’m going to use an OpenAPI specification, my reasoning:
- It will allow me to draft some abstract concepts on-the-fly
- OpenAPI itself is well documented (less explaining to do, for now)
- No need to build a client for every language I play with
- Generating tests based on this schema is TDD (plus more avenues of future content)
This is a contract-first approach at building the application. The specification I design will be used as a contract which I will later fulfil when I build the API, itself.
The Specification (First Draft)
It has taken me about an hour to to write and validate using this Swagger Validator.
swagger: "2.0"
info:
title: Hello REST
description: A friendly RESTful API
version: 1.0.0
host: 192.168.33.10
basePath: /v1
schemes:
- https
- http
paths:
/albums:
get:
summary: Search for albums
produces:
- application/json
responses:
200:
description: Here is the list of albums you requested
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/track'
"/albums/{albumId}":
get:
summary: Return an album
parameters:
- in: path
name: albumId
type: string
required: true
description: Unique ID of album
produces:
- application/json
responses:
200:
description: Here is the album you requested
schema:
$ref: '#/definitions/album'
404:
description: Album does not exist
"/albums/{albumId}/tracks":
get:
summary: Return tracks belonging to the album
parameters:
- in: path
name: albumId
type: string
required: true
description: Unique ID of album
produces:
- application/json
responses:
200:
description: Tracks belonging to album
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/track'
404:
description: Album does not exist
/artists:
get:
summary: Returns a list of albums
produces:
- application/json
responses:
200:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/album'
/tracks:
get:
summary: Search for tracks
produces:
- application/json
responses:
200:
description: Here is the list of tracks you requested
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/track'
definitions:
album:
type: object
required:
- id
- title
properties:
id:
type: string
title:
type: string
artist:
type: object
required:
- id
- title
properties:
id:
type: string
title:
type: string
track:
type: object
required:
- id
- title
properties:
id:
type: string
title:
type: string
Now that we have an idea of what we want to achieve, the next step is to build the API (it doesn’t take long)
code to pen 
One thought on “Hello REST – Designing a RESTful API”