Context ​

Context describes a single request to the app. After processing a request, the app returns a context containing a result.

How processing works is described as a pipeline. A pipeline runs in the following sequence:

1. Runs all before hooks [in sequence] installed on the app
2. Runs all before hooks [in sequence] installed on the service
3. Passes context to the service to handle.
4. The result from the service is passed [in sequence] to all after hooks installed on the service
5. Runs all after hooks [in sequence] installed on the app

The current state of the context is passed with every call to a hook in the pipeline or the service.

See the structure of a context here.

A context is normally created by the server and passed to the app with app.api(ctx)

Methods ​

In Mangobase, the following methods are used. It exists in the context as ctx.method.

create ​

The equivalent HTTP method is POST. It is used to create a new resource. When you make a POST request to /songs for example, this is a create request.

Using the Fetch API, this will look like:

// The API endpoint is [conventionally] prefixed with `/api`
const data = {
  title: 'Hello',
  artist: 'Adele',
}

fetch('/api/songs', {
  method: 'POST',
  body: JSON.stringify(data),
})

// The API endpoint is [conventionally] prefixed with `/api`
const data = {
  title: 'Hello',
  artist: 'Adele',
}

fetch('/api/songs', {
  method: 'POST',
  body: JSON.stringify(data),
})

A successful call to create will return a 201 status code with the created resource in the response body.

find ​

The equivalent HTTP method is GET. It is used to retrieve a list of resources. A GET request to /songs for example is a find request. This method is intended to always return a paginated response in the following format:

interface PaginatedResponse {
  data: any[]
  total: number
  limit: number
  skip: number
}

interface PaginatedResponse {
  data: any[]
  total: number
  limit: number
  skip: number
}

In frontend code, this will look like:

fetch('/api/songs', {
  method: 'GET',
})

fetch('/api/songs', {
  method: 'GET',
})

The response will look like:

{
  "data": [
    {
      "id": 1,
      "title": "Hello",
      "artist": "Adele"
    },
    {
      "id": 2,
      "title": "Someone Like You",
      "artist": "Adele"
    }
  ],
  "total": 2,
  "limit": 10,
  "skip": 0
}

{
  "data": [
    {
      "id": 1,
      "title": "Hello",
      "artist": "Adele"
    },
    {
      "id": 2,
      "title": "Someone Like You",
      "artist": "Adele"
    }
  ],
  "total": 2,
  "limit": 10,
  "skip": 0
}

If you wanted to limit the number of items returned, you can pass a limit query parameter. For example, /songs?$limit=1 will return only one item.

Pagination is done using the skip query parameter. For example, /songs?$skip=5 will skip the first 5 items.

get ​

Making a GET request to /songs/1 for example is get. This method is intended to always return a single item.

In frontend code, this will look like:

fetch('/api/songs/1', {
  method: 'GET',
})

fetch('/api/songs/1', {
  method: 'GET',
})

A status code of 404 will be returned if the item is not found.

update ​

The equivalent HTTP method is PATCH. It is used to update a single resource. For example, when you make a PATCH request to /songs/1.

remove ​

The equivalent HTTP method is DELETE. A DELETE request to /songs/1 for example, this is a remove request. Note that this requires the id of the resource to be passed as a parameter.

Invalid requests ​

As far as Mangobase is concerned, some requests like the following are not supported:

• POST /songs/1 - You cannot create an item on a detail path.
• PATCH /songs - You cannot patch a base path.
• DELETE /songs - You cannot delete a base path.
• PUT - Mangobase does not support PUT requests.