API Configuration files

❓ What is a configuration file?

An API configuration file is written in a .yaml and is loaded into the API at runtime, it consists of all of your API configuration, including rules and routing and because it is loaded in at runtime there is no database and ultra-fast request handling.

⚙️ What does it consist of?

😄 A name

The name of the configuration which becomes the type or version of your API, e.g. you can have a configuration for web and one for mobile, or a configuration for version 1 or version 2. This allows you to route similar requests from different clients to different places, i.e. a mobile app could hit a lighter configuration to minimise network usage, whereas a web client could use endpoints which return more data. Maybe you introduced a breaking change into your API and you need a new version to keep existing clients happy, or your new flashy UI might want to contact a newer version of the API, you can do that too.

Examples

name: "/web/v2"

name: "/mobile/v1"

💻 Endpoints

Your API has endpoints right? This is the next things contained in your configuration, the endpoints you want to expose to the client and outside world, these will map through to destinations within your ecosystem, passing through variables using a semicolon notation e.g. :user_id

Examples

name: "/web/v2"
  endpoints:
    - url: /me

name: "/mobile/v1"
  endpoints:
    - url: /comments

📮 Methods

Each endpoint can have up to four methods; GET, PUT, POST, DELETE

Examples

name: "/web/v2"
  endpoints:
    - url: /me
      methods:
        - method: GET

name: "/mobile/v1"
  endpoints:
    - url: /comments
      methods:
        - method: POST

🔒 Roles

Roles will check the claims of the trusted user to check if they have a role and if they are allowed to access and endpoint, no role, no dice (unless you make it wildcard *, then anyone authenticated can use the endpoint). Roles is an array to allow you to specify any number of roles of which only one is required to reach the endpoint.

Examples

name: "/web/v2"
  endpoints:
    - url: /me
      methods:
        - method: GET
          roles:
            - *

name: "/mobile/v1"
  endpoints:
    - url: /comments
      methods:
        - method: POST
          roles:
            - admin

👤 Scopes

Scopes will only allow the endpoint to be accessed if the user has given the client the authority to perform the action, such as read:profile or post:comments. Scopes is an array to allow you to specify any number of scopes of which only one is required to reach the endpoint.

name: "/web/v2"
  endpoints:
    - url: /me
      methods:
        - method: GET
          roles:
            - *
          scopes:
            - read:profile

name: "/mobile/v1"
  endpoints:
    - url: /comments
      methods:
        - method: POST
          roles:
            - admin
          scopes:
            - post:comments

🏖 Destinations

Every endpoint has a least one destination, this is where the gateway will forward the request on to for the request to be handled, exposing the right endpoints of your microservices to the outside world and hiding others. This is really simple for PUT, POST and DELETE requests; endpoints and destinations have a one-to-one relationship. However, GET requests can have multiple destinations for a single endpoint, this is known as Request Bundling and helps to speed up your API by making the gateway do multiple GET requests rather than the client.

Variables are passed through using the same semicolon notation used in the endpoint specification e.g. :user_id

Examples

name: "/web/v2"
  endpoints:
    - url: /me
      methods:
        - method: GET
          roles:
            - *
          scopes:
            - read:profile
          destination:
            name: profile
            host: http://users-microservice
            url: /user/profile

name: "/mobile/v1"
  endpoints:
    - url: /comments
      methods:
        - method: POST
          roles:
            - admin
          scopes:
            - post:comments
          destination:
            name: comments
            host: http://comments-microservice
            url: /comments/:comment_id

🚫 Breaking the rules

If any request breaks the rules, such as not having the correct role or the correct scope, then the API will return a 404 error exactly the same as if the endpoint wasn't there in the first place, this keeps things secure in production, but can be really annoying in development, so can be turned off via an environmental variable API_DEV_MODE=true which enables Dev Mode.

🌲 Configuration hierarchy

An API configuration hierarchy looks like the below:

configuration
|
└───endpoint 1
|   |
│   └───method 1
|   |   |
│   |   └───roles
|   |   |
│   |   └───scopes
|   |   |
│   |   └───destination 1
|   |   |
│   |   └───destination 2
|   |   |
│   |   └───destination 3
|   |
│   └───method 2
|       |
│       └───roles
|       |
│       └───scopes
|       |
│       └───destination 1
|
└───endpoint 2
    |
    └───method 1
    |   |
    |   └───roles
    |   |
    |   └───scopes
    |   |
    |   └───destination 1
    |
    └───method 2
        |
        └───roles
        |
        └───scopes
        |
        └───destination 1