API Guidelines

Introduction

Alm Brand APIs are organized around REST and focuses on:

a common look and feel.
a general API, abstracted from specific implementation and use cases.
API products, composed of one or more APIs, that support specific client use cases.
robust and easy to use API.
tracking API changes as revisions (non-breaking changes)
avoiding API versioning (breaking changes), but use them as a final resort.
deprecating and retiring old APIs, and announce it in well advance to consumers.

REST style

Alm Brand APIs support the following REST style

modelled in Open Api v3
prefer application/json to transport data
resource names must be lower-cased with hypens, verb-free and in plural,
property names and query parameters in snake-case
errors are modelled using application/problem+json
collection resources having standard way of handling pagination
date and date-time property names ends with '_at'

Revisions & Versioning

Alm Brand's APIs follow, as far as possible, the API expand-contract pattern, which supports parallel changes in the same way as used for databases or code. For example, first adding to an API while deprecating an existing element, and then only later removing the deprecated elements once consumers are switched to the newer schema.
For those APIs where this is not possible, header versioning is used.

Show Case

The example below shows how Alm brand REST style can be used to describe a todo-list api.

Open Api Spec

The Open api spec must have the following boilerplate information in the top
See more about Open Api here - https://github.com/OAI/OpenAPI-Specification

openapi: 3.0.1
info:
  title: Todo list API
  description: Manages your todo list>
  termsOfService: https://developer.almbrand.dk/terms
  contact:
    name: API Team
    url: https://developer.almbrand.dk
    email: api@almbrand.dk
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: /todo-list
externalDocs:
  description: Developer Documentation
  url: https://developer.almbrand.dk
tags:
  - name: Todo
    description: Some toto description

Create todo

The POST method is used for creating a new todo.

POST /todo-list/todos
Host: https://preprod-api.almbrand.dk
Content-Type: application/json
Authorization: Bearer {{access_token}}
ocp-apim-subscription-key: {{subcription_key}}
{ 
  "title": "Walk the dog",
  "description" : "Remember to use the LED light dog collar",
  "due_at" : "2020-12-01T07:00:00Z"
}

200 ok
Content-Type: applcation/json
{ 
  "todo_id" : "f3ebd242-853d-44f1-97e7-9db83af1a130"
  "title": "Walk the dog",
  "description" : "Remember to use the LED light dog collar",
  "due_at" : "2020-12-10T07:00:00Z",
  "created_at" : "2020-12-1T12:00:00Z" 
}

If the call fails one of following problem responses can be expected:
(see problem specification - https://tools.ietf.org/html/rfc7807)

400 Bad Request
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.io/todo-list/problems",
    "title": "Constraint Violation",
    "status": 400,
    "violations": [
        {
            "field": "due_at",
            "message": "Must not be in the past"
        }
    ]
}

401 Unauthorized
Content-Type: applcation/problem+json
WWW-Authenticate scope=[ required scope to access the requested resource is mssing ]
{
    "type": "https://developer.almbrand.io/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401
}

500 Internal Server Error
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.io/problems/internal-server-error",
    "title": "Internal Server Error",
    "status": 500
}

Retrieve one todo

The GET method and the quote_id is used for retrieving a specific todo.
The todo_id is obtained when the todo is created or by searching the todo list

GET /todo-list/todos/f3ebd242-853d-44f1-97e7-9db83af1a130
Host: https://preprod-api.almbrand.dk
Content-Type: application/json
Authorization: Bearer {{access_token}}
ocp-apim-subscription-key: {{subcription_key}}

200 ok
Content-Type: applcation/json
{ 
  "todo_id" : "f3ebd242-853d-44f1-97e7-9db83af1a130"
  "title": "Walk the dog",
  "description" : "Remember to use the LED light dog collar",
  "due_at" : "2020-12-10T07:00:00Z",
  "created_at" : "2020-12-1T12:00:00Z" 
}

If the call fails one of following problem responses can be expected:
(see problem specification - https://tools.ietf.org/html/rfc7807)

404 Not Found
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.dk/problems/not-found",
    "title": "Unauthorized",
    "status": 401
}

401 Unauthorized
(See create todo example)

500 Internal Server Error
(See create todo example)

Retrieve todo list

The GET method is used for retrieving all specific todos.
The answer is divided into pages, stating the number, size, total number of elements and pages. As well as links to the following and previous pages

GET /todo-list/todos
Host: https://preprod-api.almbrand.dk
Content-Type: application/json
Authorization: Bearer {{access_token}}
ocp-apim-subscription-key: {{subcription_key}}

200 ok
Content-Type: applcation/json
{
   "elements" : [
    {
        "todo_id" : "f3ebd242-853d-44f1-97e7-9db83af1a130",
        "title": "Walk the dog",
        "description" : "Remember to use the LED light dog collar",
        "due_at" : "2020-12-10T07:00:00Z",
        "created_at" : "2020-12-1T12:00:00Z"
    }
    {}.{},{},{},{},{},{},{},{}
   ],
   "page" : { 
    "size" : 10,
    "total_elements" : 11,
    "total_pages" : 2,
    "number" : 0
  },
  "_links" : {
    "next" : {
      "href" : "http://preprod-api.almbrand.dk/todo-list/todos?page=1&size=10"
    }
  }
}

If the call fails one of following problem responses can be expected:
(see problem specification - https://tools.ietf.org/html/rfc7807)

400 Bad Request
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.dk/todo-list/problems",
    "title": "Constraint Violation",
    "status": 400,
    "violations": [
      {
        "field": "page",
        "message": "is not an integer"
      }
    ]
}

401 Unauthorized
(See create todo example)

500 Internal Server Error
(See create todo example)

Search todo list

Both GET and POST method is used to search in the todo list by some criteria.
If no match is found an empty list i returned.
Otherwise answer is divided into pages, stating the number, size, total number of elements and pages. As well as links to the following and previous pages.

Using GET

GET /todo-list/todos?due_at=2020-12-10
Host: https://preprod-api.almbrand.dk
Content-Type: application/json
Authorization: Bearer {{access_token}}
ocp-apim-subscription-key: {{subcription_key}}

200 OK 
(same response as retrieve all todos)

200 ok - if no elements found
Content-Type: applcation/json
{
   "elements" : [],
   "page" : { 
    "size" : 10,
    "total_elements" : 1,
    "total_pages" : 1,
    "number" : 0
  },
  "_links" : {
  }
}

If the call fails one of following problem responses can be expected:
(see problem specification - https://tools.ietf.org/html/rfc7807)

400 Bad Request
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.dk/todo-list/problems",
    "title": "Constraint Violation",
    "status": 400,
    "violations": [
      {
        "field": "due_at",
        "message": "is not a valid date"
      }
    ]
}

401 Unauthorized
(See create todo example)

500 Internal Server Error
(See create todo example)

Using POST

GET /todo-list/todos/search
Host: https://preprod-api.almbrand.dk
Content-Type: application/json
Authorization: Bearer {{access_token}}
ocp-apim-subscription-key: {{subcription_key}}
{
    "due_at" : "2020-12-10"
}

200 OK 
(same response as retrieve all todos)

200 ok - if no elements found
Content-Type: applcation/json
{
   "elements" : [],
   "page" : { 
    "size" : 10,
    "total_elements" : 1,
    "total_pages" : 1,
    "number" : 0
  },
  "_links" : {
  }
}

If the call fails one of following problem responses can be expected:
(see problem specification - https://tools.ietf.org/html/rfc7807)

400 Bad Request
Content-Type: applcation/problem+json
{
    "type": "https://developer.almbrand.dk/todo-list/problems",
    "title": "Constraint Violation",
    "status": 400,
    "violations": [
      {
        "field": "due_at",
        "message": "is not a valid date"
      }
    ]
}

401 Unauthorized
(See create todo example)

500 Internal Server Error
(See create todo example)