Service Specification and APIs

Get introduced to the product's service and define its specification and API endpoints.

We'll cover the following

In this course, we will create a service using both pure and impure ways. Before we start developing the service, we need to define its specification and the APIs that it will expose.

Let’s define the specification first.

Service specification

First of all, we need to specify the exact scope and API of the project(service) that we will be developing. We’ll design the service with a minimal API to keep things simple and easy to understand.

The service shall provide HTTP API endpoints for:

  1. the creation of a product data type identified by a unique id;
  2. adding language translations for a product name by language code and a unique id;
  3. returning the existing translations for a product;
  4. returning a list of all existing products with their translations.

Data model

We will keep the model very simple in order to avoid going overboard with the implementation.

  1. A language code shall be defined by the ISO 639-1.
  2. A translation shall contain a language code and a product name (non-empty string).
  3. A product shall contain a unique id (UUID version 4) and a list of translations.

Database

The data will be stored in a relational database (RDBMS). Therefore, we need to define the tables and relations within the database.

The products table

The table “products” must only contain the unique id, which is also the primary key.

The names table

The table “names” must contain a column for the product id, one for the language code, and one for the name. Its primary key is the combination of the product id and the language code. All columns must not be null.

The relation to the products is realized by a foreign key constraint to the products table via the product id.

HTTP API

The HTTP API shall provide the following endpoints on the given paths:

Path HTTP Method Function
/products POST Create a product
/products GET Get all products and translations
/product/{UUID} PUT Update product
/product/{UUID} GET Get the specific product

The data shall be encoded in JSON using the following specifications:

Press + to interact
{  
    "lang": "ISO-639-1 Code",
    "name": "A non empty string."
}
Press + to interact
{
    "id": "The-UUID-of-the-product",
    "names": [
        // A list of translations.
    ] 
}

Let’s get started!