@servicenow/sdk

--- tags: [RestApi, rest api, api, endpoint, web service, scripted rest, sys_ws_definition, sys_ws_operation, sys_ws_version, HTTP, route] --- # RestApi Creates endpoints, query parameters, and headers for a scripted REST service (`sys_ws_definition`). ## Signature ```typescript fluent RestApi(api) ``` ## Parameters ### api `RestApi<I, ApiVersion<I>>` **Properties:** - **$id** (required): `string | number | ExplicitKey<string>` - **name** (required): `string` The name of the API, which is used in the API documentation. - **$meta** (optional): `object` - **installMethod**: `'first install' | 'demo' | 'once'` Map a record to an output folder that loads only in specific circumstances. 'first install' - > 'unload', 'demo' -> 'unload.demo' - **active** (optional): `boolean` Indicates whether the API can serve requests - **consumes** (optional): `string` A list of media types that resources of the API can consume - **docLink** (optional): `string` A URL that links to static documentation about the API - **enforceAcl** (optional): `(string | Acl<unknown, AclType>)[]` A list of ACLs to enforce when accessing resources (`sys_security_acl`) - **protectionPolicy** (optional): `'' | 'read' | 'protected'` The policy for how application files are protected when downloaded or installed - **policy** (optional, deprecated): `'' | 'read' | 'protected'` Deprecated. Use `protectionPolicy` instead. - **produces** (optional): `string` A list of media types that resources of the API can produce - **routes** (optional): `(object)[] | Route[]` The resources (`sys_ws_operation`) for the API - **$id**: `string | number | ExplicitKey<string>` - **script**: `string | (request: any, response: any) => void` The script that processes the request and generates a response. Use a JavaScript module import (preferred) or `Now.include()` for legacy non-modular scripts. See the `module-guide` topic. - **version**: `V['version']` - **active**: `boolean` If true, the endpoint is active and can receive requests. - **authentication**: `boolean` If true, the endpoint requires authentication. - **authorization**: `boolean` If true, the endpoint requires authorization. - **consumes**: `string` MIME type that the endpoint can consume. - **enforceAcl**: `(string | Acl<unknown, AclType>)[]` List of ACLs that control access to this endpoint. - **headers**: `RouteHeader[]` List of headers that the endpoint accepts or requires. - **$id**: `string | number | ExplicitKey<string>` - **name**: `string` The name of the header. - **exampleValue**: `string` An example value for the header. - **required**: `boolean` Indicates whether the header is required for the request. - **shortDescription**: `string` A brief description of the header. - **internalRole**: `boolean` If true, the endpoint is only accessible to users with the internal role. - **method**: `'GET' | 'DELETE' | 'PATCH' | 'POST' | 'PUT'` The HTTP method for the endpoint. Defaults to 'GET' if not specified. - **name**: `string` The name of the endpoint. This is displayed in the API documentation. - **parameters**: `RouteParameter[]` List of parameters that the endpoint accepts. - **$id**: `string | number | ExplicitKey<string>` - **name**: `string` The name of the parameter. - **exampleValue**: `string` An example value for the parameter. - **required**: `boolean` Indicates whether the parameter is required for the request. - **shortDescription**: `string` A brief description of the parameter. - **path**: `string` The URL path for the endpoint, relative to the API's base URL. - **protectionPolicy**: `'' | 'read' | 'protected'` The policy for how application files are protected when downloaded or installed. - **policy** (deprecated): `'' | 'read' | 'protected'` Deprecated. Use `protectionPolicy` instead. - **produces**: `string` MIME type that the endpoint produces. - **requestExample**: `string` An example request payload for the endpoint. - **shortDescription**: `string` A brief description of the endpoint. - **serviceId** (required): `string` The API identifier used to distinguish this API in URI paths. It must be unique within the API namespace - **shortDescription** (optional): `string` A brief description of the API, which is used in the API documentation - **versions** (optional): `ApiVersion<I>[]` A list of versions (`sys_ws_version`) for the API - **$id**: `string | number | ExplicitKey<string>` - **version**: `I` The version number of the API. - **active**: `boolean` Indicates whether the API version is active and can receive requests. - **deprecated**: `boolean` Indicates whether the API version is deprecated. - **isDefault**: `boolean` Indicates whether this is the default version of the API. - **shortDescription**: `string` A brief description of the API version. ## See - https://docs.servicenow.com/csh?topicname=scripted-rest-api-api-now-ts.html&version=latest ## Examples ### CRUD REST API Create a REST API with GET, PUT, and DELETE operations ```typescript fluent /** * @title CRUD REST API * @description Create a REST API with GET, PUT, and DELETE operations */ import { RestApi } from '@servicenow/sdk/core' RestApi({ $id: Now.ID['restapi-crud'], name: 'CRUD REST API', serviceId: 'restapi_crud', consumes: 'application/json', routes: [ { $id: Now.ID['restapi-crud-get'], name: 'get', method: 'GET', script: ` (function process(request, response) { response.setBody({ message: 'GET request' }) })(request, response) `, }, { $id: Now.ID['restapi-crud-put'], name: 'put', method: 'PUT', script: ` (function process(request, response) { var reqbody = request.body.dataString; var parser = new global.JSON(); var parsedData = parser.decode(reqbody); response.setBody({ put: parsedData }) })(request, response) `, }, { $id: Now.ID['restapi-crud-delete'], name: 'delete', method: 'DELETE', script: ` (function process(request, response) { response.setBody({ delete: { msg: "DELETED" } }) })(request, response) `, }, ], }) ``` ### Simple REST API Create a REST API with GET and POST routes using inline scripts ```typescript fluent /** * @title Simple REST API * @description Create a REST API with GET and POST routes using inline scripts */ import { RestApi } from '@servicenow/sdk/core' RestApi({ $id: Now.ID['restapi-hello'], name: 'rest api fluent sample', serviceId: 'restapi_hello', consumes: 'application/json', routes: [ { $id: Now.ID['restapi-hello-get'], name: 'get', method: 'GET', script: ` (function process( /*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) { response.setBody({ message: 'Hello, World!' }) })(request, response) `, }, { $id: Now.ID['restapi-hello-post'], name: 'post', method: 'POST', script: ` (function process( /*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) { var reqbody = request.body.dataString; var parser = new global.JSON(); var parsedData = parser.decode(reqbody); response.setBody({ post: parsedData }) })(request, response) `, }, ], }) ``` ### REST API with Module Handler Create a REST API that uses an imported TypeScript module for the route handler ```typescript fluent /** * @title REST API with Module Handler * @description Create a REST API that uses an imported TypeScript module for the route handler */ import { RestApi } from '@servicenow/sdk/core' import { process } from '../../modules/RestApi/rest-api-handler' RestApi({ $id: Now.ID['restapi-modules'], name: 'rest api fluent modules sample', serviceId: 'restapi_modules', consumes: 'application/json', routes: [ { $id: Now.ID['restapi-modules-get'], name: 'get', method: 'GET', script: process, }, ], }) ``` **rest-api-handler.ts** ```typescript fluent import { gs } from '@servicenow/glide' export function process(request: any, response: any) { gs.info('Processing REST API request') response.setBody({ message: 'Hello from module!' }) } ```