스크립트 기반 REST API

The scripted REST API feature allows application developers to build custom web service APIs.

You can define service endpoints, query parameters, and headers for a scripted REST API, as well as scripts to manage the request and response.

Scripted REST APIs generally follow the REST architecture, but you can customize them to use different conventions. You define scripted REST APIs using the Scripted REST Service form found under Scripted Web Services → Scripted REST APIs.

그림 1. 스크립팅된 REST 서비스 양식

The following videos offer additional information about scripted REST APIs:

• Scripted REST APIs – Design
• Scripted REST APIs – Implementation

Scripted REST API URIs

Scripted REST API URIs have the following format:

https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>

In this URI:

• <instance.service-now.com>: Path to the ServiceNow instance where users access the scripted REST API.
• <name_space>: For web services in the global scope, the name space is the value of the property glide.appcreator.company.code. For web services in a scoped application, the name space is the scope name, such as x_company_appname. For additional information on name spaces, see Application scope.
• <version>: Optional. Version of the endpoint to access if the API uses versioning, such as v1. You can access the default version of a versioned API by specifying the URI without a version number.
• <api_id>: Value of the API ID field on the Scripted REST Service form. By default this value is based on the service name.
• <relative_path>: Relative path defined for the resource in the Scripted REST Service form. Specifying a relative resource path allows you to have multiple resources using the same HTTP method, such as GET, in one web service. For example, a resource may specify the path /{id} when the web service has only one GET resource, or /user/{id} and /message/{id} when the web service has different resources for requesting user and message records.

Scripted REST API versioning

Scripted REST API URIs may include a version number, such as /api/management/v1/table/{tableName}. Version numbers identify the endpoint version that a URI accesses. By specifying a version number in your URIs, you can test and deploy changes without impacting existing integrations.

Default API version

A version may be marked as default. Specifying a default version allows users to access that version using a scripted REST endpoint without a version number. If no version is marked as default, the latest version is used as the default.

Scripted REST API resources

A scripted REST API resource is equivalent to a REST endpoint. It defines the HTTP method to execute, the processing script, and any override settings from the parent API. You can define one ore more resources per API.

Scripted REST API query parameters

Query parameters define values that requesting users can pass in a request. When creating a scripted REST API, you can specify which parameters are available and which are mandatory for each request. You can also associate a query parameter with multiple resources.

Access request parameters in scripts using the request object queryParams field.

Scripted REST API roles

To work with scripted REST APIs, you must have the web service administrator [web_service_admin] role. Users with this role can read, create, modify, and delete scripted REST APIs and web service resources.

주:

These roles are not required to access a scripted REST API endpoint.

Request and response formats

기본적으로 API의 모든 자원은 application/json, application/xml 및 text/xml의 요청 및 응답 형식을 지원합니다. You can overrride the default formats at the API level. The new formats apply to all resources belonging to the API, unless an individual resource overrides the defaults.

Scripted REST API security

You can configure your scripted REST APIs with the necessary level of security. From public APIs/endpoints that don't require any security to highly secure APIs/endpoints that require user authentication with tight access control to all resources.

Scripted REST API access controls

Access control lists (ACLs) define criteria, such as the roles needed and conditions that a user must meet to access a scripted REST API or endpoint. A requesting user must satisfy at least one of the ACLs. It is not necessary to satisfy all selected ACLs. You can define a single ACL for an entire REST API or for an individual endpoint.

주:

By default, scripted REST APIs contain an ACL that prohibits users with the snc_external role from making requests to the API.

When defining a scripted REST API ACL, it must have the Type value REST_Endpoint.

For additional information on ACLs, see Access control list rules and ACL을 요구하도록 스크립트된 REST API 자원 구성.

Scripted REST API security matrix

There are multiple possible security configurations for scripted REST APIs. Use this table to identify the scripted REST API security configuration that best suits your needs, and the field values to implement that configuration.

표 1. Scripted REST API security

구성	Scripted REST APIs	스크립팅된 REST 자원
	기본 ACL	인증 필요	ACL 권한 필요	ACL
The resource is public. No authentication or ACL is required.	Any value	아니오	Any value	Any value
The resource requires basic authentication only. No ACL is required.	Any value	예	아니오	Any value
The resource requires basic authentication only. ACL is required.	No ACL selected	예	예	No ACL selected
An ACL selected in the resource record is required.	Any value	예	예	One or more ACLs selected
An ACL selected in the scripted REST API record is required.	One or more ACLs selected	예	예	No ACL selected

Scripted REST API error objects

Scripted REST APIs include error objects that allow you to respond to a request with a standard HTTP error message when an error occurs during request processing. You can use error objects in scripted REST API resources to alert requesting clients of errors. Use error objects to respond to incoming requests, not to catch errors within your server-side code.

Error response format

The content type of the response depends on the request Accept header. If the Accept header specifies an unsupported format, such as image/jpeg, the error response uses JSON.

Error responses follow this format:

{
  "error": {
    "message": "My error message",
    "detail": "My details"  
  },  
  "status": "failure"
}

The numeric status code, such as 404, is included in the response Status code header, not in the response body.

Automated Test Framework support

Automated Test Framework(ATF)는 인바운드 REST 테스트 단계를 지원합니다. 직접 만든 사용자 지정 인바운드 REST API에 대한 자동화된 테스트를 만들 수 있습니다. 사용자 지정 REST API에 대한 테스트를 만들면 업그레이드 테스트가 간소화되고 REST API에 대한 수정 사항이 이전 버전과 호환되는지 확인할 수 있습니다. REST 테스트 단계 구성 관리 및 ATF REST 테스트 단계 구성의 내용을 참조하십시오.

개발자 교육

In the ServiceNow® 개발자 사이트, you can find training for Scripted REST APIs.

• Scripted REST API 생성
  웹 서비스 엔드포인트를 정의하는 Scripted REST API를 만듭니다.
• 스크립팅된 REST API 모범 사례
  스크립팅된 REST API를 디자인하고 구현할 때 다음 지침을 따르십시오.
• Scripted REST API examples
  Mutliple examples are available demonstrating how to create and use scripted REST APIs.