Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform App Engine
Table of Contents
Choose your release version
    Home Orlando Now Platform App Engine Now Platform App Engine Web services Scripted REST APIs

    Scripted REST APIs

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

    Scripted REST APIs

    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.

    Figure 1. Scripted REST Service form
    Scripted REST Service form

    The following podcast offers additional information on the use of scripted REST APIs.

    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.
    Note: These roles are not required to access a scripted REST API endpoint.

    Request and response formats

    By default, all resources in an API support the following request and response formats: application/json, application/xml, and 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.

    Note: 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 Configure a scripted REST API resource to require an ACL.

    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.

    Table 1. Scripted REST API security
    Configuration Scripted REST API Scripted REST Resource
    Default ACLs Requires authentication Requires ACL authorization ACLs
    The resource is public. No authentication or ACL is required. Any value False Any value Any value
    The resource requires basic authentication only. No ACL is required. Any value True False Any value
    The resource requires basic authentication only. ACL is required. No ACL selected True True No ACL selected
    An ACL selected in the resource record is required. Any value True True One or more ACLs selected
    An ACL selected in the scripted REST API record is required. One or more ACLs selected True True 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

    The Automated Test Framework (ATF) supports Inbound REST test steps. You can create automated tests for custom Inbound REST APIs that you create. Creating tests for your custom REST APIs simplifies upgrade testing, and makes it possible to verify that modifications to a REST API are backward compatible. See Administering REST test step configurations and ATF REST test step configurations.

    Developer training

    In the ServiceNow® Developer Site, you can find training for Scripted REST APIs.

    • Create a scripted REST API

      Create a scripted REST API to define web service endpoints.

    • Scripted REST APIs good practices

      Follow these guidelines when designing and implementing scripted REST APIs.

    • Scripted REST API examples

      Mutliple examples are available demonstrating how to create and use scripted REST APIs.

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      Scripted REST APIs

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

      Scripted REST APIs

      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.

      Figure 1. Scripted REST Service form
      Scripted REST Service form

      The following podcast offers additional information on the use of scripted REST APIs.

      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.
      Note: These roles are not required to access a scripted REST API endpoint.

      Request and response formats

      By default, all resources in an API support the following request and response formats: application/json, application/xml, and 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.

      Note: 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 Configure a scripted REST API resource to require an ACL.

      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.

      Table 1. Scripted REST API security
      Configuration Scripted REST API Scripted REST Resource
      Default ACLs Requires authentication Requires ACL authorization ACLs
      The resource is public. No authentication or ACL is required. Any value False Any value Any value
      The resource requires basic authentication only. No ACL is required. Any value True False Any value
      The resource requires basic authentication only. ACL is required. No ACL selected True True No ACL selected
      An ACL selected in the resource record is required. Any value True True One or more ACLs selected
      An ACL selected in the scripted REST API record is required. One or more ACLs selected True True 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

      The Automated Test Framework (ATF) supports Inbound REST test steps. You can create automated tests for custom Inbound REST APIs that you create. Creating tests for your custom REST APIs simplifies upgrade testing, and makes it possible to verify that modifications to a REST API are backward compatible. See Administering REST test step configurations and ATF REST test step configurations.

      Developer training

      In the ServiceNow® Developer Site, you can find training for Scripted REST APIs.

      • Create a scripted REST API

        Create a scripted REST API to define web service endpoints.

      • Scripted REST APIs good practices

        Follow these guidelines when designing and implementing scripted REST APIs.

      • Scripted REST API examples

        Mutliple examples are available demonstrating how to create and use scripted REST APIs.

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login