Resources are defined by a name and a collection of methods. Each method can be configured with properties that define how the request is constructed.

Key configuration properties for a method definition include:

• path: The URL path. Supports dynamic segments like {id} (required), {group} (with defaults), or {market?} (optional).
• method: The HTTP method (e.g., 'post', 'put').
• host: An alternative host for this specific method.
• headers: Default headers for the method.
• params: Default parameters for the method.
• binary: Set to true if the response is binary data (returns a Buffer in Node.js or a Blob in the browser).
• bodyAttr, headersAttr, authAttr, timeoutAttr, signalAttr, hostAttr, pathAttr: Used to specify a custom parameter name if the default special parameter (like body or headers) cannot be used by your API.

const client = forge({
  resources: {
    User: {
      all: { path: '/users' },
      byId: { path: '/users/{id}' },
      byGroup: { path: '/users/groups/{group}', params: { group: 'general' } },
      count: { path: '/{market?}/users' } 
    },
    Blog: {
      create: { method: 'post', path: '/blogs', headers: { 'X-Special-Header': 'value' } },
      bySubject: { path: '/blogs', queryParamAlias: { subjectId: 'subject_id' } },
      byDate: { path: ({date}) => `${date.getYear()}/${date.getMonth()}/${date.getDate()}` }
    }
  }
})

Middleware allows you to customize the behavior between your client and the API. A middleware is a function that returns an object containing two optional methods: prepareRequest and response.

The prepareRequest phase

prepareRequest is used to modify the request before it is sent. It receives a next function which, when called, returns a Promise resolving to the Request object. You can use request.enhance() to create a new request based on the previous one.

The response phase

response is used to modify the response after it is received. It receives a next function which, when called, returns a Promise resolving to the Response object. You can use response.enhance() to create a new response based on the previous one.

Passing information between middleware

You can pass information from an earlier middleware to a later one using the request context via request.enhance({}, { key: 'value' }) and retrieving it with request.getContext().

const MyMiddleware = () => ({
  prepareRequest(next) {
    return next().then(request => request.enhance({
      headers: { 'x-special-request': '->' }
    }))
  }
})

const MyMiddlewareTwo = () => ({
  async prepareRequest(next) {
    const request = await next()
    const { message } = request.getContext()
    console.log(message)
    return request
  }
})
// Order in forge: middleware: [MyMiddlewareOne, MyMiddlewareTwo]

Middleware can be applied at three different levels. When multiple levels are used, they are applied in the following order: Resource level $\rightarrow$ Client level $\rightarrow$ Global level.

1. Resource level: Applied only to specific resources or methods within a client. Configured in the resources section of the manifest.
2. Client level: Applied to all resources within a specific client. Configured in the root of the forge manifest.
3. Global level: Applied to all clients created via forge. Configured via the configs.middleware object.

Note: Global middleware can be disabled for a specific client by setting ignoreGlobalMiddleware: true in the forge configuration.

// Resource level
const client = forge({
  resources: {
    User: { all: { middleware: [ MyMiddleware ], path: '/users' } }
  }
})

// Client level
const client = forge({
  middleware: [ MyMiddleware ],
  resources: { User: { all: { path: '/users' } } }
})

// Global level
import { configs } from 'mappersmith'
configs.middleware = [ MyMiddleware ]

To create an API client, provide a manifest object to the forge function. The manifest defines a host (optional if the API is on the same domain) and a resources object. Each resource contains named methods that map to specific API paths.

Note: You must configure a gateway (e.g., Fetch) via configs.gateway before using the client.

import forge, { configs } from "mappersmith"
import { Fetch } from "mappersmith/gateway/fetch"

// Configure the gateway
configs.gateway = Fetch;

const github = forge({
  clientId: "github",
  host: "https://www.githubstatus.com",
  resources: {
    Status: {
      current: { path: "/api/v2/status.json" },
      summary: { path: "/api/v2/summary.json" },
      components: { path: "/api/v2/components.json" },
    },
  },
});

// Call a resource method
git-hub.Status.current().then((response) => {
  console.log(`summary`, response.data());
});