Defining an API Config
API Config file structure#
The following is a condensed example of the API Config file structure:
{ "endpoints": { "<endpoint-name>": { "paths":[ { "path": "/assets", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } }, ... ] }, ... }, "schema_version": 2, "settings": { "apiConfig": true }}| Property | Type | Description |
|---|---|---|
| endpoints | Object | Contains each endpoint object you want to define |
| <endpoint-name> | Object | A named endpoint that contains a "paths" array of objects that define each endpoint path. Note: The attribute names in the endpoints object must match the path name. For example, if you have an endpoint-name called "status" then the path should be /status. |
| paths | Array of Object | An array of path definition objects |
| path | String | The endpoint URL path. Note: This must match the endpoint-name. |
| method | String | HTTP request type, such as "GET", or "PUT". |
| script._userType | String | Name of the script file to reference |
| script._scriptName | String | Name of the script function you want to call from the script file defined in script._userType |
| schema_version | Number | Set to 2 to enable the use of JavaScript scripts to back your endpoints |
| settings.apiConfig | Boolean | Set to true to declare the file as an API Config file |
API config file example
{ "endpoints": { "assets": { "paths":[ { "path":"/assets", "method": "OPTIONS", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "optionsScript" } }, { "path":"/assets", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } }, { "path":"/assets", "method": "POST", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "addAssets" } }, { "path":"/assets/:assetid", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "extractAssetById" } }, { "path":"/assets/:assetid", "method": "PUT", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "editAssets" } }, { "path":"/assets/:assetid", "method": "DELETE", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "delAssets" } }, { "path":"/assets/search", "method": "POST", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "searchAssets" } }, { "path":"/assets/:assetid/documents", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getDocumentsForAsset" } }, { "path":"/assets/:assetid/documents", "method": "POST", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "addDocumentForAsset" } }, { "path":"/assets/:assetid/documents", "method": "DELETE", "script": { "_userType": "iaf_obj_model_api_assets", "_scriptName": "delDocumentsForAsset" } }, { "path":"/assets/:assetid/documents/download", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "downloadDocumentForAsset" } } ] }, "spaces": { "paths":[ { "path":"/spaces", "method": "GET", "script": "getSpaces" } ] } }, "schema_version": 2, "settings": { "apiConfig": true }}Defining endpoints#
The endpoints object contains parameters that define endpoint groups. Each named endpoint object defines a group of endpoint path configurations.
{ "endpoints": { "assets": {<all asset endpoint path configurations>}, "spaces": {<all space endpoint path configurations>} }}Configuring endpoint paths#
A named endpoint group contains an array of endpoint path configuration objects, which are the various endpoint paths exposed by the API. To add path variables, see Accessing path variables. For example, if the resource “assets” exposes GET and POST methods, then you must define two path configuration objects.
You can only use one method per path configuration object so you must create a new one for each method.
In the following example, when the "/assets" endpoint is called with a GET method, the "iaf_obj_model_api_assets" script file is loaded and the "getAssets" script executes:
{ "endpoints": { "asset": { "paths":[ ... { "path":"/assets", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } }, ... ] } }}
OPTIONS paths#
For any endpoints to work when requests are made from a browser, you must add an OPTIONS path as the base path for each resource.
When dealing with CORS requests, browsers make pre-flight requests to each endpoint's OPTIONS method before making the call itself. If you do not supply OPTIONS paths, all requests to your endpoints will fail in a browser.
The OPTIONS path requires a script, but it need simply return any value, as reponse values are ignored for OPTIONS.
The following example demonstrates the OPTIONS path for the asset endpoint:
{ "endpoints": { "asset": { "paths":[ { "path":"/assets", "method": "OPTIONS", //OPTIONS method "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "optionsScript" //Script designated to handle OPTIONS response } }, { "path":"/assets", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } }, ... ] } }}
Adding path variables to an endpoint#
To add a path variable to your endpoint path, pre-fix the lowercase variable name with a colon, :, for example, :variable_name:
{ "endpoints": { "asset": { "paths":[ { "path":"/assets/:assetid", //asset id variable "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } } ] } }}
You can add more than one path variables to a path:
{ "endpoints": { "asset": { "paths":[ { "path":"/assets/:assetid/documents/:documentid", "method": "GET", "script":{ "_userType": "iaf_obj_model_api_assets", "_scriptName": "getAssets" } } ] } }}
Note: For more information on accessing path variables from a script, see Accessing path variables.