API Reference
class APIDeclaration
method configure
Purpose
Configures papupata for implementing or calling APIs.Usage
This method must be called before any of the declared APIs are implemented or called. Failure to having done so will cause the operation to fail.Parameters
| Name | Type | Description |
|---|---|---|
| config | Config | Configuration. See below. Instead of an actual config null can be provided to unconfigure papupata, which can be useful to reset things for tests, for example. |
Returns
Nothingconfig object
Members
| Name | Type | Data type/return type | Description | Required | Introduced in | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| baseURL | property | string | Base URL used for all API invocations. This can be an empty string, in which case the calls on the browser are made relative to the root of the current host. | Conditionally *1 | |||||||||||||||||||||||||||||||||
requestAdapter makeRequest (deprecated) | property | Function | This function is used internally for calling APIs. The function is as follows: Parameters
ReturnsPromise<any>; the promise, on a successful request, should resolve with the response type of the declared request. Typically this means parsing the JSON data.Two adapters are supplied with papupata, one for fetch and one for request-promise. | Conditionally *2 | |||||||||||||||||||||||||||||||||
| app | property | Express application | Express application, on which the declared APIs will be attached. If you make sure all the api declarations are invoked as the routing is being set up then using the application is fine, but if there is a chance that routes will be added later then the router is the better option. | Conditionally *3 | |||||||||||||||||||||||||||||||||
| router | property | Express router | Express router, on which the declared APIs will be attached. The main advantage of using a router over app is that APIs can be added after the whole application has been configured, assuming no middleware is added to the router itself after the routes. | Conditionally *3 | |||||||||||||||||||||||||||||||||
| routerAt | property | string | It often makes sense to declare APIs on top a common base URL. In practice though you might have a router set up for a specific path, for example to add common middleware. By setting routerAt, you explicitly indicate that the provided router will be at the given path. All routes on an API declaration with routerAt MUST have the routerAt as the start of their path. | 1.4.0 | |||||||||||||||||||||||||||||||||
| inherentMiddleware | property | Function[] | An array of papupata middleware applied to all routes implemented in this API declaration, that is, middleware inherent to all routes of this declaration. Only relevant for implementing, not for clients. | 1.5.0 | |||||||||||||||||||||||||||||||||
| autoImplementAllAPIs | property | boolean | Note: the overall effect is the same, as in 1.x, it's just that the default value is true rather than false in 2.x. By default, all declared but unimplemented routes are automatically set up to return 501 not implemented as a response to requests. If there is an app or router present at the time of declaration, this happens immediately, otherwise it happens as soon as an app or router is configured. This can be prevented by setting this configuration option to false. This two major effect; for one, attempts to call unimplemented papupata APIs end up going to other route handlers or middleware (this can be accomplished for individual routes with either returning skipHandlingRoute or by disabling auto-implementation just for it). Also, routes end up being implemented not in the order they were implemented in, rather than their declaration order. Usually this does not make a big difference, but if you have two handlers that can match the same path, say, /api/:var and /api/fixed, the only way requests ever reached fixed was if it was implemented first. With this variable set to true, it has to be declared first, but the implementation order is irrelevant. | 1.5.0 | |||||||||||||||||||||||||||||||||
| validationBehavior | property | ValidationBehavior | Query and path parameter types introduced in 2.0.0 include validations. This option can be used to determine what happens when a validation fails, for example a string that cannot be converted to a number is sent in a context where a number is expected. The ValidationBehavior enum can be imported from papupata/config
Individual APIs can override this behavior using their own validationBehavior option. | 2.0.0 |
Examples
Common to examples below:
For all examples below, it is assumed that the API declaration happens in ./api.ts such as this:api.ts
import {APIDeclaration} from 'papupata'
export const api = new APIDeclaration()Simple server configuration
import express from 'express'
import {api} from './api'
const app = express()
api.configure({
application: app
})
Server with router
import express, {Router} from 'express'
import {api} from './api'
const app = express()
const router = new Router()
app.use(router)
api.configure({
router
})
Configuring browser to use fetch from the local host
import {api} from './api'
import {fetchAdapter} from 'papupata/adapters/fetch'
api.configure({
baseURL: '',
requestAdapter: fetchAdapter
})