<h2>Scripted REST APIs good practices</h2><br/><div style="overflow-x:auto"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta content="text/html; charset=UTF-8" /><meta name="copyright" content="(C) Copyright 2024" /><meta name="DC.rights.owner" content="(C) Copyright 2024" /><meta name="generator" content="DITA-OT" /><meta name="DC.type" content="concept" /><meta name="DC.title" content="Scripted REST APIs good practices" /><meta name="abstract" content="Follow these guidelines when designing and implementing scripted REST APIs." /><meta name="description" content="Follow these guidelines when designing and implementing scripted REST APIs." /><meta name="DC.relation" scheme="URI" content="../../../../integrate/custom-web-services/concept/c_CustomWebServices.html" /><meta name="DC.relation" scheme="URI" content="../../../../build/custom-application/reference/r_CustomApplicationDevelopment.html" /><meta name="DC.relation" scheme="URI" content="../../../../integrate/web-services/reference/r_AvailableWebServices.html" /><meta name="DC.relation" scheme="URI" content="../../../../integrate/web-services/concept/inbound-web-services.html" /><meta name="DC.relation" scheme="URI" content="../../../../integrate/inbound-rest/concept/c_RESTAPI.html" /><meta name="DC.creator" content="ServiceNow" /><meta name="DC.date.created" content="2022-08-04" /><meta name="DC.date.modified" content="2022-08-04" /><meta name="mini-toc" content="yes" /><meta name="DC.format" content="XHTML" /><meta name="DC.identifier" content="scripted-rest-good-practices" /><link rel="stylesheet" type="text/css" href="../../../../CSS/commonltr.css" /><title>Scripted REST APIs good practices</title></head><body id="scripted-rest-good-practices"> <div class="breadcrumb"><a class="link" href="../../../../build/custom-application/reference/r_CustomApplicationDevelopment.html" title="The Now Platform provides a single mobile and web application development platform to build business applications and extend existing apps that power your digital transformation.">Hyperautomation and Low-Code</a> > <a class="link" href="../../../../integrate/web-services/reference/r_AvailableWebServices.html" title="HTTP-based web services allow diverse applications to talk to each other. ServiceNow supports both inbound (provider) and outbound (consumer) web services.">Integrate with ServiceNow</a> > <a class="link" href="../../../../integrate/web-services/concept/inbound-web-services.html" title="You can use any of several web services to integrate with ServiceNow applications, including REST, SOAP, JSONv2, and RSS.">Inbound web services</a> > <a class="link" href="../../../../integrate/inbound-rest/concept/c_RESTAPI.html" title="REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.">REST APIs</a> > </div> <h1 class="title topictitle1" id="ariaid-title1">Scripted REST APIs good practices</h1> <div class="body conbody"><p class="shortdesc">Follow these guidelines when designing and implementing scripted REST APIs.</p> <div class="section" id="scripted-rest-good-practices__section_xwf_flr_23b"><h2 class="title sectiontitle">Follow REST API conventions</h2> <p class="p">Use REST API standards to provide a consistent and easy to use interface for clients. REST API conventions define specific behavior for each type of method. Use the following guidelines as a starting point for designing your API.</p> <div class="p"><ul class="ul" id="scripted-rest-good-practices__ul_tbd_3lr_23b"><li class="li"><span class="keyword parmname">GET</span> operations only query data. A GET request should never modify data.</li><li class="li"><span class="keyword parmname">POST</span> operations create new records but do not modify existing records.</li><li class="li"><span class="keyword parmname">PUT</span> and <span class="keyword parmname">PATCH</span> operations modify existing records.</li><li class="li"><span class="keyword parmname">DELETE</span> operations destroy records.</li></ul> </div> </div> <div class="section" id="scripted-rest-good-practices__section_km4_mlr_23b"><h2 class="title sectiontitle">Use versioning to control changes to your API</h2> <p class="p">Use versioning to implement new functionality and avoid breaking existing integrations. When you introduce significant functionality changes to your API, create a new version of the API first. Do not introduce behavior that will break existing integrations in a published version.</p> <p class="p">Using versioning allows you to implement significant changes to your API without breaking existing clients. You can then release the new version of the API for new clients while allowing existing clients to upgrade at their own pace.</p> <p class="p">Encourage clients to use a version-specific API, or configure the API without a default version to force clients to specify a version. You can also make new, optional behavior available by adding an optional parameter to an existing version.</p> </div> <div class="section" id="scripted-rest-good-practices__section_xbn_qlr_23b"><h2 class="title sectiontitle">Return an informative HTTP status code</h2> <p class="p">Return a status code that informs the requestor of the success or failure of the request. Return an HTTP status code that helps the client understand the result of the request. Use the following guidelines for common status codes.</p> <div class="p"> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="scripted-rest-good-practices__table_cbv_2rh_dw" class="table" frame="border" border="1" rules="all"><caption><span class="tablecap"><span class="table--title-label">Table 1. </span>Common status codes</span></caption><colgroup><col /><col /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d158508e113">Status code</th><th class="entry cellrowborder" style="vertical-align:top;" id="d158508e116">Description</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e113 ">200</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e116 ">Indicates that the request was completed successfully.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e113 ">201</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e116 ">Indicates that a record was created successfully.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e113 ">204</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e116 ">Indicates that a record was deleted successfully.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e113 ">40X (401, 404)</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e116 ">Status codes in the 400 range indicate a client error, such as 400 for invalid request syntax.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e113 ">50X (500, 503)</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d158508e116 ">Status codes in the 500 range indicate that a server error occurred. The client request may have been valid or invalid, but a problem occurred on the server that prevented it from processing the request.</td></tr></tbody></table> </div> </div> </div> <div class="section" id="scripted-rest-good-practices__section_gwd_vlr_23b"><h2 class="title sectiontitle">Return useful error information</h2> <p class="p">Provide the client with enough information in error messages to allow them to understand the problem without having to refer to your API documentation. An error response should include a helpful error message, as well as an error status code.</p> <p class="p">For example, when a client queries a record that does not exist, you can return the error message "The specified record does not exist. Ensure that a record with the ID of <id value> exists in the application." along with a 404 status code.</p> <p class="p">The scripted REST API feature includes several preconfigured error objects you can use for commonly-encountered errors, and a customizable ServiceRequest error object you can use when the preconfigured error objects do not meet your needs.</p> </div> <div class="section" id="scripted-rest-good-practices__section_efh_1mr_23b"><h2 class="title sectiontitle">Enforce and test access controls</h2> <p class="p">Enforce existing access controls and require additional access to modify data. In addition to requiring authentication to access the API, require authorization to access data. Use the <span class="keyword apiname">GlideRecordSecure</span> API in your scripted REST API scripts. This API ensures that access controls defined on the underlying data are applied for the requesting user.</p> <p class="p">Require additional access controls for operations that modify data. Requests such as PUT, POST, and DELETE should require a higher level of access than GET. Configure these API resources to require a more strict ACL.</p> <p class="p">Test your access controls, both authentication and authorization, before releasing the API.</p> </div> <div class="section" id="scripted-rest-good-practices__section_hlf_hmr_23b"><h2 class="title sectiontitle">Build tests to verify functionality</h2> <p class="p">Build tests that verify your scripted REST web services functionality as part of your development process. Use repeatable tests to ensure that your API functions the way you expect it to. Testing also helps ensure that changes you make do not affect the expected API behavior after you release a version. You can use a REST client application that supports automated testing, such as Postman, to facilitate testing.</p> <p class="p">Tests should validate the response code, headers, and body content as appropriate for each resource you implement. You can also use tests to validate authentication requirements, and to confirm that errors return useful responses.</p> </div> </div> <div class="related-links"> <div class="familylinks"> <div class="parentlink"><strong>Parent Topic:</strong> <a class="link" href="../../../../integrate/custom-web-services/concept/c_CustomWebServices.html" title="The scripted REST API feature allows application developers to build custom web service APIs.">Scripted REST APIs</a></div> </div> </div></body></html></div>