[{"data":1,"prerenderedAt":1928},["ShallowReactive",2],{"page-\u002Fblog\u002Fservicenow-scripted-rest-api-example\u002F":3,"related-\u002Fblog\u002Fservicenow-scripted-rest-api-example\u002F":1903},{"id":4,"title":5,"author":6,"authorUrl":7,"body":8,"date":1876,"dateUpdated":1876,"description":1877,"dqid":1876,"excerpt":1878,"extension":1879,"faq":1880,"headline":5,"meta":1893,"navigation":290,"path":1894,"seo":1895,"socialImage":1896,"stem":1897,"tags":1898,"__hash__":1902},"content\u002Fblog\u002Fservicenow-scripted-rest-api-example.md","Scripted REST API ServiceNow Example: Build One End to End","Gabriel Fordan","https:\u002F\u002Fsn-tricks.com\u002Fabout",{"type":9,"value":10,"toc":1866},"minimark",[11,20,29,34,37,87,102,106,143,153,169,173,183,209,215,222,827,830,879,887,891,894,915,918,1339,1359,1389,1393,1400,1422,1437,1441,1454,1457,1563,1566,1689,1692,1761,1775,1779,1794,1798,1849,1862],[12,13,14,15,19],"p",{},"This scripted REST API ServiceNow example builds a small incident API from scratch: one GET resource that returns an incident by number, one POST resource that adds a comment, and the security and testing steps that make it usable. Create the API under ",[16,17,18],"strong",{},"System Web Services > Scripted Web Services > Scripted REST APIs",", add a resource for each method and path, write the handler script, then call it with curl or the REST API Explorer. Each step is below with working code.",[12,21,22,23,28],{},"If you already know the basics and want design rules, read the companion guide on ",[24,25,27],"a",{"href":26},"\u002Fblog\u002Fservicenow-scripted-rest-api-best-practices","Scripted REST API best practices",". This article is the hands-on version.",[30,31,33],"h2",{"id":32},"what-we-are-building","What we are building",[12,35,36],{},"Two endpoints, inside a scoped application on a development instance:",[38,39,40,56],"table",{},[41,42,43],"thead",{},[44,45,46,50,53],"tr",{},[47,48,49],"th",{},"Method",[47,51,52],{},"Path",[47,54,55],{},"Purpose",[57,58,59,74],"tbody",{},[44,60,61,65,71],{},[62,63,64],"td",{},"GET",[62,66,67],{},[68,69,70],"code",{},"\u002Fapi\u002F\u003Cscope>\u002Fincident_api\u002F{number}",[62,72,73],{},"Return a summary of one incident",[44,75,76,79,84],{},[62,77,78],{},"POST",[62,80,81],{},[68,82,83],{},"\u002Fapi\u002F\u003Cscope>\u002Fincident_api\u002F{number}\u002Fcomment",[62,85,86],{},"Add a customer-visible comment",[12,88,89,90,93,94,97,98,101],{},"Replace ",[68,91,92],{},"\u003Cscope>"," with your application scope, for example ",[68,95,96],{},"x_acme_support",". The GET endpoint also accepts an optional ",[68,99,100],{},"fields"," query parameter so the caller can ask for a smaller response.",[30,103,105],{"id":104},"step-1-create-the-api-record","Step 1: Create the API record",[107,108,109,113,123,140],"ol",{},[110,111,112],"li",{},"Open your scoped application in Studio, or set it as your current application.",[110,114,115,116,118,119,122],{},"Navigate to ",[16,117,18],{}," and select ",[16,120,121],{},"New",".",[110,124,125,126,129,130,133,134,129,137,122],{},"Set ",[16,127,128],{},"Name"," to ",[68,131,132],{},"Incident API"," and ",[16,135,136],{},"API ID",[68,138,139],{},"incident_api",[110,141,142],{},"Save.",[12,144,145,146,149,150,122],{},"The form now shows the ",[16,147,148],{},"Base API path",", built from the namespace and the API ID. For a scoped application the namespace is the scope name, so the base path looks like ",[68,151,152],{},"\u002Fapi\u002Fx_acme_support\u002Fincident_api",[12,154,155,156,159,160,163,164,168],{},"The API record lives in ",[68,157,158],{},"sys_ws_definition",". Each resource you add next lives in ",[68,161,162],{},"sys_ws_operation",". Both are captured in your ",[24,165,167],{"href":166},"\u002Fblog\u002Fservicenow-update-sets-complete-guide-migration-mastery","update set"," along with the rest of the application.",[30,170,172],{"id":171},"step-2-add-the-get-resource","Step 2: Add the GET resource",[12,174,175,176,179,180,182],{},"In the ",[16,177,178],{},"Resources"," related list, select ",[16,181,121],{}," and fill in:",[184,185,186,195,201],"ul",{},[110,187,188,191,192],{},[16,189,190],{},"Name:"," ",[68,193,194],{},"Get incident",[110,196,197,200],{},[16,198,199],{},"HTTP method:"," GET",[110,202,203,191,206],{},[16,204,205],{},"Relative path:",[68,207,208],{},"\u002F{number}",[12,210,211,212,122],{},"The braces define a path parameter. Whatever the caller puts in that segment arrives in ",[68,213,214],{},"request.pathParams.number",[12,216,217,218,221],{},"Paste this into the ",[16,219,220],{},"Script"," field:",[223,224,229],"pre",{"className":225,"code":226,"language":227,"meta":228,"style":228},"language-javascript shiki shiki-themes github-light github-light","(function process(\u002F*RESTAPIRequest*\u002F request, \u002F*RESTAPIResponse*\u002F response) {\n    var number = request.pathParams.number;\n\n    if (!\u002F^INC\\d+$\u002F.test(number)) {\n        return new sn_ws_err.BadRequestError('Expected an incident number such as INC0010001');\n    }\n\n    \u002F\u002F GlideRecordSecure applies the caller's ACLs to the query and fields\n    var inc = new GlideRecordSecure('incident');\n    inc.addQuery('number', number);\n    inc.setLimit(1);\n    inc.query();\n\n    if (!inc.next()) {\n        return new sn_ws_err.NotFoundError('No incident found with number ' + number);\n    }\n\n    var allowed = ['number', 'short_description', 'state', 'priority', 'assignment_group', 'assigned_to', 'sys_updated_on'];\n    var requested = allowed;\n\n    \u002F\u002F Each query parameter value is an array of strings\n    if (request.queryParams.fields && request.queryParams.fields[0]) {\n        requested = request.queryParams.fields[0].split(',').filter(function (f) {\n            return allowed.indexOf(f.trim()) > -1;\n        }).map(function (f) {\n            return f.trim();\n        });\n    }\n\n    var body = { sys_id: inc.getUniqueValue() };\n    requested.forEach(function (field) {\n        body[field] = {\n            value: inc.getValue(field),\n            display_value: inc.getDisplayValue(field)\n        };\n    });\n\n    response.setStatus(200);\n    response.setBody(body);\n})(request, response);\n","javascript","",[68,230,231,270,285,292,331,354,360,365,371,393,410,425,436,441,459,482,487,492,540,553,558,564,584,624,656,675,687,693,698,703,722,742,753,765,777,783,789,794,810,821],{"__ignoreMap":228},[232,233,236,240,244,248,250,254,258,261,264,267],"span",{"class":234,"line":235},"line",1,[232,237,239],{"class":238},"sKWpL","(",[232,241,243],{"class":242},"sCydW","function",[232,245,247],{"class":246},"se37E"," process",[232,249,239],{"class":238},[232,251,253],{"class":252},"sJ8bj","\u002F*RESTAPIRequest*\u002F",[232,255,257],{"class":256},"sj_tP"," request",[232,259,260],{"class":238},", ",[232,262,263],{"class":252},"\u002F*RESTAPIResponse*\u002F",[232,265,266],{"class":256}," response",[232,268,269],{"class":238},") {\n",[232,271,273,276,279,282],{"class":234,"line":272},2,[232,274,275],{"class":242},"    var",[232,277,278],{"class":238}," number ",[232,280,281],{"class":242},"=",[232,283,284],{"class":238}," request.pathParams.number;\n",[232,286,288],{"class":234,"line":287},3,[232,289,291],{"emptyLinePlaceholder":290},true,"\n",[232,293,295,298,301,304,308,311,314,318,321,323,325,328],{"class":234,"line":294},4,[232,296,297],{"class":242},"    if",[232,299,300],{"class":238}," (",[232,302,303],{"class":242},"!",[232,305,307],{"class":306},"sOTlB","\u002F",[232,309,310],{"class":242},"^",[232,312,313],{"class":306},"INC",[232,315,317],{"class":316},"sMN4m","\\d",[232,319,320],{"class":242},"+$",[232,322,307],{"class":306},[232,324,122],{"class":238},[232,326,327],{"class":246},"test",[232,329,330],{"class":238},"(number)) {\n",[232,332,334,337,340,343,346,348,351],{"class":234,"line":333},5,[232,335,336],{"class":242},"        return",[232,338,339],{"class":242}," new",[232,341,342],{"class":238}," sn_ws_err.",[232,344,345],{"class":246},"BadRequestError",[232,347,239],{"class":238},[232,349,350],{"class":306},"'Expected an incident number such as INC0010001'",[232,352,353],{"class":238},");\n",[232,355,357],{"class":234,"line":356},6,[232,358,359],{"class":238},"    }\n",[232,361,363],{"class":234,"line":362},7,[232,364,291],{"emptyLinePlaceholder":290},[232,366,368],{"class":234,"line":367},8,[232,369,370],{"class":252},"    \u002F\u002F GlideRecordSecure applies the caller's ACLs to the query and fields\n",[232,372,374,376,379,381,383,386,388,391],{"class":234,"line":373},9,[232,375,275],{"class":242},[232,377,378],{"class":238}," inc ",[232,380,281],{"class":242},[232,382,339],{"class":242},[232,384,385],{"class":246}," GlideRecordSecure",[232,387,239],{"class":238},[232,389,390],{"class":306},"'incident'",[232,392,353],{"class":238},[232,394,396,399,402,404,407],{"class":234,"line":395},10,[232,397,398],{"class":238},"    inc.",[232,400,401],{"class":246},"addQuery",[232,403,239],{"class":238},[232,405,406],{"class":306},"'number'",[232,408,409],{"class":238},", number);\n",[232,411,413,415,418,420,423],{"class":234,"line":412},11,[232,414,398],{"class":238},[232,416,417],{"class":246},"setLimit",[232,419,239],{"class":238},[232,421,422],{"class":316},"1",[232,424,353],{"class":238},[232,426,428,430,433],{"class":234,"line":427},12,[232,429,398],{"class":238},[232,431,432],{"class":246},"query",[232,434,435],{"class":238},"();\n",[232,437,439],{"class":234,"line":438},13,[232,440,291],{"emptyLinePlaceholder":290},[232,442,444,446,448,450,453,456],{"class":234,"line":443},14,[232,445,297],{"class":242},[232,447,300],{"class":238},[232,449,303],{"class":242},[232,451,452],{"class":238},"inc.",[232,454,455],{"class":246},"next",[232,457,458],{"class":238},"()) {\n",[232,460,462,464,466,468,471,473,476,479],{"class":234,"line":461},15,[232,463,336],{"class":242},[232,465,339],{"class":242},[232,467,342],{"class":238},[232,469,470],{"class":246},"NotFoundError",[232,472,239],{"class":238},[232,474,475],{"class":306},"'No incident found with number '",[232,477,478],{"class":242}," +",[232,480,481],{"class":238}," number);\n",[232,483,485],{"class":234,"line":484},16,[232,486,359],{"class":238},[232,488,490],{"class":234,"line":489},17,[232,491,291],{"emptyLinePlaceholder":290},[232,493,495,497,500,502,505,507,509,512,514,517,519,522,524,527,529,532,534,537],{"class":234,"line":494},18,[232,496,275],{"class":242},[232,498,499],{"class":238}," allowed ",[232,501,281],{"class":242},[232,503,504],{"class":238}," [",[232,506,406],{"class":306},[232,508,260],{"class":238},[232,510,511],{"class":306},"'short_description'",[232,513,260],{"class":238},[232,515,516],{"class":306},"'state'",[232,518,260],{"class":238},[232,520,521],{"class":306},"'priority'",[232,523,260],{"class":238},[232,525,526],{"class":306},"'assignment_group'",[232,528,260],{"class":238},[232,530,531],{"class":306},"'assigned_to'",[232,533,260],{"class":238},[232,535,536],{"class":306},"'sys_updated_on'",[232,538,539],{"class":238},"];\n",[232,541,543,545,548,550],{"class":234,"line":542},19,[232,544,275],{"class":242},[232,546,547],{"class":238}," requested ",[232,549,281],{"class":242},[232,551,552],{"class":238}," allowed;\n",[232,554,556],{"class":234,"line":555},20,[232,557,291],{"emptyLinePlaceholder":290},[232,559,561],{"class":234,"line":560},21,[232,562,563],{"class":252},"    \u002F\u002F Each query parameter value is an array of strings\n",[232,565,567,569,572,575,578,581],{"class":234,"line":566},22,[232,568,297],{"class":242},[232,570,571],{"class":238}," (request.queryParams.fields ",[232,573,574],{"class":242},"&&",[232,576,577],{"class":238}," request.queryParams.fields[",[232,579,580],{"class":316},"0",[232,582,583],{"class":238},"]) {\n",[232,585,587,590,592,594,596,599,602,604,607,610,613,615,617,619,622],{"class":234,"line":586},23,[232,588,589],{"class":238},"        requested ",[232,591,281],{"class":242},[232,593,577],{"class":238},[232,595,580],{"class":316},[232,597,598],{"class":238},"].",[232,600,601],{"class":246},"split",[232,603,239],{"class":238},[232,605,606],{"class":306},"','",[232,608,609],{"class":238},").",[232,611,612],{"class":246},"filter",[232,614,239],{"class":238},[232,616,243],{"class":242},[232,618,300],{"class":238},[232,620,621],{"class":256},"f",[232,623,269],{"class":238},[232,625,627,630,633,636,639,642,645,648,651,653],{"class":234,"line":626},24,[232,628,629],{"class":242},"            return",[232,631,632],{"class":238}," allowed.",[232,634,635],{"class":246},"indexOf",[232,637,638],{"class":238},"(f.",[232,640,641],{"class":246},"trim",[232,643,644],{"class":238},"()) ",[232,646,647],{"class":242},">",[232,649,650],{"class":242}," -",[232,652,422],{"class":316},[232,654,655],{"class":238},";\n",[232,657,659,662,665,667,669,671,673],{"class":234,"line":658},25,[232,660,661],{"class":238},"        }).",[232,663,664],{"class":246},"map",[232,666,239],{"class":238},[232,668,243],{"class":242},[232,670,300],{"class":238},[232,672,621],{"class":256},[232,674,269],{"class":238},[232,676,678,680,683,685],{"class":234,"line":677},26,[232,679,629],{"class":242},[232,681,682],{"class":238}," f.",[232,684,641],{"class":246},[232,686,435],{"class":238},[232,688,690],{"class":234,"line":689},27,[232,691,692],{"class":238},"        });\n",[232,694,696],{"class":234,"line":695},28,[232,697,359],{"class":238},[232,699,701],{"class":234,"line":700},29,[232,702,291],{"emptyLinePlaceholder":290},[232,704,706,708,711,713,716,719],{"class":234,"line":705},30,[232,707,275],{"class":242},[232,709,710],{"class":238}," body ",[232,712,281],{"class":242},[232,714,715],{"class":238}," { sys_id: inc.",[232,717,718],{"class":246},"getUniqueValue",[232,720,721],{"class":238},"() };\n",[232,723,725,728,731,733,735,737,740],{"class":234,"line":724},31,[232,726,727],{"class":238},"    requested.",[232,729,730],{"class":246},"forEach",[232,732,239],{"class":238},[232,734,243],{"class":242},[232,736,300],{"class":238},[232,738,739],{"class":256},"field",[232,741,269],{"class":238},[232,743,745,748,750],{"class":234,"line":744},32,[232,746,747],{"class":238},"        body[field] ",[232,749,281],{"class":242},[232,751,752],{"class":238}," {\n",[232,754,756,759,762],{"class":234,"line":755},33,[232,757,758],{"class":238},"            value: inc.",[232,760,761],{"class":246},"getValue",[232,763,764],{"class":238},"(field),\n",[232,766,768,771,774],{"class":234,"line":767},34,[232,769,770],{"class":238},"            display_value: inc.",[232,772,773],{"class":246},"getDisplayValue",[232,775,776],{"class":238},"(field)\n",[232,778,780],{"class":234,"line":779},35,[232,781,782],{"class":238},"        };\n",[232,784,786],{"class":234,"line":785},36,[232,787,788],{"class":238},"    });\n",[232,790,792],{"class":234,"line":791},37,[232,793,291],{"emptyLinePlaceholder":290},[232,795,797,800,803,805,808],{"class":234,"line":796},38,[232,798,799],{"class":238},"    response.",[232,801,802],{"class":246},"setStatus",[232,804,239],{"class":238},[232,806,807],{"class":316},"200",[232,809,353],{"class":238},[232,811,813,815,818],{"class":234,"line":812},39,[232,814,799],{"class":238},[232,816,817],{"class":246},"setBody",[232,819,820],{"class":238},"(body);\n",[232,822,824],{"class":234,"line":823},40,[232,825,826],{"class":238},"})(request, response);\n",[12,828,829],{},"A few details worth noticing:",[184,831,832,838,856,864],{},[110,833,834,837],{},[16,835,836],{},"Validate the path parameter first."," The regular expression rejects anything that is not an incident number before a query runs.",[110,839,840,849,850,852,853,855],{},[16,841,842,845,846,122],{},[68,843,844],{},"GlideRecordSecure"," instead of ",[68,847,848],{},"GlideRecord"," The API runs as the authenticated caller, and ",[68,851,844],{}," enforces that caller's read ACLs on rows and fields. A plain ",[68,854,848],{}," would return data the caller is not allowed to see.",[110,857,858,863],{},[16,859,860,861,122],{},"An allowlist for ",[68,862,100],{}," The caller can narrow the response but cannot ask for fields you did not intend to expose.",[110,865,866,871,872,875,876,122],{},[16,867,868,870],{},[68,869,817],{}," wraps the object."," ServiceNow returns your object inside a ",[68,873,874],{},"result"," property, so the caller receives ",[68,877,878],{},"{\"result\": {...}}",[12,880,881,882,886],{},"For larger lookups, the same query rules from the ",[24,883,885],{"href":884},"\u002Fblog\u002Fservicenow-gliderecord-query-performance","GlideRecord query performance guide"," apply: filter on indexed fields and limit the rows you read.",[30,888,890],{"id":889},"step-3-add-the-post-resource","Step 3: Add the POST resource",[12,892,893],{},"Add a second resource:",[184,895,896,903,908],{},[110,897,898,191,900],{},[16,899,190],{},[68,901,902],{},"Add comment",[110,904,905,907],{},[16,906,199],{}," POST",[110,909,910,191,912],{},[16,911,205],{},[68,913,914],{},"\u002F{number}\u002Fcomment",[12,916,917],{},"Script:",[223,919,921],{"className":225,"code":920,"language":227,"meta":228,"style":228},"(function process(\u002F*RESTAPIRequest*\u002F request, \u002F*RESTAPIResponse*\u002F response) {\n    var number = request.pathParams.number;\n    var data = request.body.data;   \u002F\u002F parsed JSON body; read it once\n\n    if (!data || typeof data.comment !== 'string' || !data.comment.trim()) {\n        return new sn_ws_err.BadRequestError('Body must be JSON with a non-empty \"comment\" string');\n    }\n    if (data.comment.length > 4000) {\n        return new sn_ws_err.BadRequestError('Comment must be 4000 characters or fewer');\n    }\n\n    var inc = new GlideRecordSecure('incident');\n    inc.addQuery('number', number);\n    inc.setLimit(1);\n    inc.query();\n\n    if (!inc.next()) {\n        return new sn_ws_err.NotFoundError('No incident found with number ' + number);\n    }\n    if (!inc.canWrite()) {\n        var denied = new sn_ws_err.ServiceError();\n        denied.setStatus(403);\n        denied.setMessage('Not allowed to update this incident');\n        return denied;\n    }\n\n    inc.setValue('comments', data.comment.trim());\n    inc.update();\n\n    response.setStatus(201);\n    response.setBody({\n        number: inc.getValue('number'),\n        sys_id: inc.getUniqueValue(),\n        message: 'Comment added'\n    });\n})(request, response);\n",[68,922,923,945,955,970,974,1013,1030,1034,1052,1069,1073,1077,1095,1107,1119,1127,1131,1145,1163,1167,1182,1201,1215,1229,1236,1240,1244,1264,1273,1277,1290,1299,1313,1323,1331,1335],{"__ignoreMap":228},[232,924,925,927,929,931,933,935,937,939,941,943],{"class":234,"line":235},[232,926,239],{"class":238},[232,928,243],{"class":242},[232,930,247],{"class":246},[232,932,239],{"class":238},[232,934,253],{"class":252},[232,936,257],{"class":256},[232,938,260],{"class":238},[232,940,263],{"class":252},[232,942,266],{"class":256},[232,944,269],{"class":238},[232,946,947,949,951,953],{"class":234,"line":272},[232,948,275],{"class":242},[232,950,278],{"class":238},[232,952,281],{"class":242},[232,954,284],{"class":238},[232,956,957,959,962,964,967],{"class":234,"line":287},[232,958,275],{"class":242},[232,960,961],{"class":238}," data ",[232,963,281],{"class":242},[232,965,966],{"class":238}," request.body.data;   ",[232,968,969],{"class":252},"\u002F\u002F parsed JSON body; read it once\n",[232,971,972],{"class":234,"line":294},[232,973,291],{"emptyLinePlaceholder":290},[232,975,976,978,980,982,985,988,991,994,997,1000,1003,1006,1009,1011],{"class":234,"line":333},[232,977,297],{"class":242},[232,979,300],{"class":238},[232,981,303],{"class":242},[232,983,984],{"class":238},"data ",[232,986,987],{"class":242},"||",[232,989,990],{"class":242}," typeof",[232,992,993],{"class":238}," data.comment ",[232,995,996],{"class":242},"!==",[232,998,999],{"class":306}," 'string'",[232,1001,1002],{"class":242}," ||",[232,1004,1005],{"class":242}," !",[232,1007,1008],{"class":238},"data.comment.",[232,1010,641],{"class":246},[232,1012,458],{"class":238},[232,1014,1015,1017,1019,1021,1023,1025,1028],{"class":234,"line":356},[232,1016,336],{"class":242},[232,1018,339],{"class":242},[232,1020,342],{"class":238},[232,1022,345],{"class":246},[232,1024,239],{"class":238},[232,1026,1027],{"class":306},"'Body must be JSON with a non-empty \"comment\" string'",[232,1029,353],{"class":238},[232,1031,1032],{"class":234,"line":362},[232,1033,359],{"class":238},[232,1035,1036,1038,1041,1044,1047,1050],{"class":234,"line":367},[232,1037,297],{"class":242},[232,1039,1040],{"class":238}," (data.comment.",[232,1042,1043],{"class":316},"length",[232,1045,1046],{"class":242}," >",[232,1048,1049],{"class":316}," 4000",[232,1051,269],{"class":238},[232,1053,1054,1056,1058,1060,1062,1064,1067],{"class":234,"line":373},[232,1055,336],{"class":242},[232,1057,339],{"class":242},[232,1059,342],{"class":238},[232,1061,345],{"class":246},[232,1063,239],{"class":238},[232,1065,1066],{"class":306},"'Comment must be 4000 characters or fewer'",[232,1068,353],{"class":238},[232,1070,1071],{"class":234,"line":395},[232,1072,359],{"class":238},[232,1074,1075],{"class":234,"line":412},[232,1076,291],{"emptyLinePlaceholder":290},[232,1078,1079,1081,1083,1085,1087,1089,1091,1093],{"class":234,"line":427},[232,1080,275],{"class":242},[232,1082,378],{"class":238},[232,1084,281],{"class":242},[232,1086,339],{"class":242},[232,1088,385],{"class":246},[232,1090,239],{"class":238},[232,1092,390],{"class":306},[232,1094,353],{"class":238},[232,1096,1097,1099,1101,1103,1105],{"class":234,"line":438},[232,1098,398],{"class":238},[232,1100,401],{"class":246},[232,1102,239],{"class":238},[232,1104,406],{"class":306},[232,1106,409],{"class":238},[232,1108,1109,1111,1113,1115,1117],{"class":234,"line":443},[232,1110,398],{"class":238},[232,1112,417],{"class":246},[232,1114,239],{"class":238},[232,1116,422],{"class":316},[232,1118,353],{"class":238},[232,1120,1121,1123,1125],{"class":234,"line":461},[232,1122,398],{"class":238},[232,1124,432],{"class":246},[232,1126,435],{"class":238},[232,1128,1129],{"class":234,"line":484},[232,1130,291],{"emptyLinePlaceholder":290},[232,1132,1133,1135,1137,1139,1141,1143],{"class":234,"line":489},[232,1134,297],{"class":242},[232,1136,300],{"class":238},[232,1138,303],{"class":242},[232,1140,452],{"class":238},[232,1142,455],{"class":246},[232,1144,458],{"class":238},[232,1146,1147,1149,1151,1153,1155,1157,1159,1161],{"class":234,"line":494},[232,1148,336],{"class":242},[232,1150,339],{"class":242},[232,1152,342],{"class":238},[232,1154,470],{"class":246},[232,1156,239],{"class":238},[232,1158,475],{"class":306},[232,1160,478],{"class":242},[232,1162,481],{"class":238},[232,1164,1165],{"class":234,"line":542},[232,1166,359],{"class":238},[232,1168,1169,1171,1173,1175,1177,1180],{"class":234,"line":555},[232,1170,297],{"class":242},[232,1172,300],{"class":238},[232,1174,303],{"class":242},[232,1176,452],{"class":238},[232,1178,1179],{"class":246},"canWrite",[232,1181,458],{"class":238},[232,1183,1184,1187,1190,1192,1194,1196,1199],{"class":234,"line":560},[232,1185,1186],{"class":242},"        var",[232,1188,1189],{"class":238}," denied ",[232,1191,281],{"class":242},[232,1193,339],{"class":242},[232,1195,342],{"class":238},[232,1197,1198],{"class":246},"ServiceError",[232,1200,435],{"class":238},[232,1202,1203,1206,1208,1210,1213],{"class":234,"line":566},[232,1204,1205],{"class":238},"        denied.",[232,1207,802],{"class":246},[232,1209,239],{"class":238},[232,1211,1212],{"class":316},"403",[232,1214,353],{"class":238},[232,1216,1217,1219,1222,1224,1227],{"class":234,"line":586},[232,1218,1205],{"class":238},[232,1220,1221],{"class":246},"setMessage",[232,1223,239],{"class":238},[232,1225,1226],{"class":306},"'Not allowed to update this incident'",[232,1228,353],{"class":238},[232,1230,1231,1233],{"class":234,"line":626},[232,1232,336],{"class":242},[232,1234,1235],{"class":238}," denied;\n",[232,1237,1238],{"class":234,"line":658},[232,1239,359],{"class":238},[232,1241,1242],{"class":234,"line":677},[232,1243,291],{"emptyLinePlaceholder":290},[232,1245,1246,1248,1251,1253,1256,1259,1261],{"class":234,"line":689},[232,1247,398],{"class":238},[232,1249,1250],{"class":246},"setValue",[232,1252,239],{"class":238},[232,1254,1255],{"class":306},"'comments'",[232,1257,1258],{"class":238},", data.comment.",[232,1260,641],{"class":246},[232,1262,1263],{"class":238},"());\n",[232,1265,1266,1268,1271],{"class":234,"line":695},[232,1267,398],{"class":238},[232,1269,1270],{"class":246},"update",[232,1272,435],{"class":238},[232,1274,1275],{"class":234,"line":700},[232,1276,291],{"emptyLinePlaceholder":290},[232,1278,1279,1281,1283,1285,1288],{"class":234,"line":705},[232,1280,799],{"class":238},[232,1282,802],{"class":246},[232,1284,239],{"class":238},[232,1286,1287],{"class":316},"201",[232,1289,353],{"class":238},[232,1291,1292,1294,1296],{"class":234,"line":724},[232,1293,799],{"class":238},[232,1295,817],{"class":246},[232,1297,1298],{"class":238},"({\n",[232,1300,1301,1304,1306,1308,1310],{"class":234,"line":744},[232,1302,1303],{"class":238},"        number: inc.",[232,1305,761],{"class":246},[232,1307,239],{"class":238},[232,1309,406],{"class":306},[232,1311,1312],{"class":238},"),\n",[232,1314,1315,1318,1320],{"class":234,"line":755},[232,1316,1317],{"class":238},"        sys_id: inc.",[232,1319,718],{"class":246},[232,1321,1322],{"class":238},"(),\n",[232,1324,1325,1328],{"class":234,"line":767},[232,1326,1327],{"class":238},"        message: ",[232,1329,1330],{"class":306},"'Comment added'\n",[232,1332,1333],{"class":234,"line":779},[232,1334,788],{"class":238},[232,1336,1337],{"class":234,"line":785},[232,1338,826],{"class":238},[12,1340,1341,1344,1345,1348,1349,1352,1353,1355,1356,1358],{},[68,1342,1343],{},"request.body.data"," gives you the parsed JSON. Read it once into a variable. The body is a stream that can only be consumed once, so if you read ",[68,1346,1347],{},"data"," and then ",[68,1350,1351],{},"dataString",", the second read comes back empty. Pick one: ",[68,1354,1347],{}," for parsed JSON, ",[68,1357,1351],{}," for the raw text.",[12,1360,1361,1362,1365,1366,1368,1369,1371,1372,1374,1375,1377,1378,133,1380,1383,1384,1388],{},"The ",[68,1363,1364],{},"sn_ws_err"," objects are the cleanest way to return errors. ",[68,1367,345],{}," returns 400, ",[68,1370,470],{}," returns 404, and ",[68,1373,1198],{}," lets you set any status code with ",[68,1376,802],{},", plus ",[68,1379,1221],{},[68,1381,1382],{},"setDetail",". ServiceNow formats the error body for you, so every failure has the same shape. If you prefer a shared helper for success and error envelopes, the ",[24,1385,1387],{"href":1386},"\u002Fscripts\u002Frest-api-response-helper","REST API response helper"," script include shows one approach.",[30,1390,1392],{"id":1391},"step-4-secure-the-resources","Step 4: Secure the resources",[12,1394,1395,1396,1399],{},"Open each resource and check the ",[16,1397,1398],{},"Security"," section:",[184,1401,1402,1408],{},[110,1403,1404,1407],{},[16,1405,1406],{},"Requires authentication"," should stay selected. Without it, anyone who can reach the instance can call the endpoint.",[110,1409,1410,1413,1414,1417,1418,1421],{},[16,1411,1412],{},"Requires ACL authorization"," should stay selected. New resources use the ",[16,1415,1416],{},"Scripted REST External Default"," ACL, which stops users with the ",[68,1419,1420],{},"snc_external"," role from calling the API. Open that ACL on your instance to see exactly what it checks.",[12,1423,1424,1425,1428,1429,1431,1432,1436],{},"For a real integration, create a dedicated integration user with only the roles it needs, and add an ACL of type ",[16,1426,1427],{},"REST_Endpoint"," for this API that requires a role you assign to that user. Then the endpoint ACL decides who can call the API at all, and ",[68,1430,844],{}," decides which incident data the caller can read or change. If a call fails with 403 and you cannot see why, the ",[24,1433,1435],{"href":1434},"\u002Fblog\u002Fservicenow-acl-troubleshooting-guide","ACL troubleshooting guide"," walks through finding the rule that blocked it.",[30,1438,1440],{"id":1439},"step-5-test-it","Step 5: Test it",[12,1442,1443,1444,300,1447,1450,1451,1453],{},"The fastest first test is the ",[16,1445,1446],{},"REST API Explorer",[16,1448,1449],{},"System Web Services > REST > REST API Explorer","). Choose your namespace and ",[68,1452,132],{},", pick a resource, fill in the path parameter, and send. The Explorer also generates sample code for curl and other clients.",[12,1455,1456],{},"From a terminal, use a test user on your development instance:",[223,1458,1462],{"className":1459,"code":1460,"language":1461,"meta":228,"style":228},"language-bash shiki shiki-themes github-light github-light","# GET with a field filter\ncurl -s -u 'api.test.user:password' \\\n  -H 'Accept: application\u002Fjson' \\\n  'https:\u002F\u002F\u003Cinstance>.service-now.com\u002Fapi\u002Fx_acme_support\u002Fincident_api\u002FINC0010001?fields=number,state,priority'\n\n# POST a comment\ncurl -s -u 'api.test.user:password' \\\n  -H 'Accept: application\u002Fjson' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -X POST \\\n  -d '{\"comment\": \"Customer confirmed the fix on their laptop.\"}' \\\n  'https:\u002F\u002F\u003Cinstance>.service-now.com\u002Fapi\u002Fx_acme_support\u002Fincident_api\u002FINC0010001\u002Fcomment'\n","bash",[68,1463,1464,1469,1486,1496,1501,1505,1510,1522,1530,1539,1548,1558],{"__ignoreMap":228},[232,1465,1466],{"class":234,"line":235},[232,1467,1468],{"class":252},"# GET with a field filter\n",[232,1470,1471,1474,1477,1480,1483],{"class":234,"line":272},[232,1472,1473],{"class":246},"curl",[232,1475,1476],{"class":316}," -s",[232,1478,1479],{"class":316}," -u",[232,1481,1482],{"class":306}," 'api.test.user:password'",[232,1484,1485],{"class":316}," \\\n",[232,1487,1488,1491,1494],{"class":234,"line":287},[232,1489,1490],{"class":316},"  -H",[232,1492,1493],{"class":306}," 'Accept: application\u002Fjson'",[232,1495,1485],{"class":316},[232,1497,1498],{"class":234,"line":294},[232,1499,1500],{"class":306},"  'https:\u002F\u002F\u003Cinstance>.service-now.com\u002Fapi\u002Fx_acme_support\u002Fincident_api\u002FINC0010001?fields=number,state,priority'\n",[232,1502,1503],{"class":234,"line":333},[232,1504,291],{"emptyLinePlaceholder":290},[232,1506,1507],{"class":234,"line":356},[232,1508,1509],{"class":252},"# POST a comment\n",[232,1511,1512,1514,1516,1518,1520],{"class":234,"line":362},[232,1513,1473],{"class":246},[232,1515,1476],{"class":316},[232,1517,1479],{"class":316},[232,1519,1482],{"class":306},[232,1521,1485],{"class":316},[232,1523,1524,1526,1528],{"class":234,"line":367},[232,1525,1490],{"class":316},[232,1527,1493],{"class":306},[232,1529,1485],{"class":316},[232,1531,1532,1534,1537],{"class":234,"line":373},[232,1533,1490],{"class":316},[232,1535,1536],{"class":306}," 'Content-Type: application\u002Fjson'",[232,1538,1485],{"class":316},[232,1540,1541,1544,1546],{"class":234,"line":395},[232,1542,1543],{"class":316},"  -X",[232,1545,907],{"class":306},[232,1547,1485],{"class":316},[232,1549,1550,1553,1556],{"class":234,"line":412},[232,1551,1552],{"class":316},"  -d",[232,1554,1555],{"class":306}," '{\"comment\": \"Customer confirmed the fix on their laptop.\"}'",[232,1557,1485],{"class":316},[232,1559,1560],{"class":234,"line":427},[232,1561,1562],{"class":306},"  'https:\u002F\u002F\u003Cinstance>.service-now.com\u002Fapi\u002Fx_acme_support\u002Fincident_api\u002FINC0010001\u002Fcomment'\n",[12,1564,1565],{},"A successful GET returns something like:",[223,1567,1571],{"className":1568,"code":1569,"language":1570,"meta":228,"style":228},"language-json shiki shiki-themes github-light github-light","{\n  \"result\": {\n    \"sys_id\": \"...\",\n    \"number\": { \"value\": \"INC0010001\", \"display_value\": \"INC0010001\" },\n    \"state\": { \"value\": \"2\", \"display_value\": \"In Progress\" },\n    \"priority\": { \"value\": \"3\", \"display_value\": \"3 - Moderate\" }\n  }\n}\n","json",[68,1572,1573,1578,1586,1600,1628,1653,1679,1684],{"__ignoreMap":228},[232,1574,1575],{"class":234,"line":235},[232,1576,1577],{"class":238},"{\n",[232,1579,1580,1583],{"class":234,"line":272},[232,1581,1582],{"class":316},"  \"result\"",[232,1584,1585],{"class":238},": {\n",[232,1587,1588,1591,1594,1597],{"class":234,"line":287},[232,1589,1590],{"class":316},"    \"sys_id\"",[232,1592,1593],{"class":238},": ",[232,1595,1596],{"class":306},"\"...\"",[232,1598,1599],{"class":238},",\n",[232,1601,1602,1605,1608,1611,1613,1616,1618,1621,1623,1625],{"class":234,"line":294},[232,1603,1604],{"class":316},"    \"number\"",[232,1606,1607],{"class":238},": { ",[232,1609,1610],{"class":316},"\"value\"",[232,1612,1593],{"class":238},[232,1614,1615],{"class":306},"\"INC0010001\"",[232,1617,260],{"class":238},[232,1619,1620],{"class":316},"\"display_value\"",[232,1622,1593],{"class":238},[232,1624,1615],{"class":306},[232,1626,1627],{"class":238}," },\n",[232,1629,1630,1633,1635,1637,1639,1642,1644,1646,1648,1651],{"class":234,"line":333},[232,1631,1632],{"class":316},"    \"state\"",[232,1634,1607],{"class":238},[232,1636,1610],{"class":316},[232,1638,1593],{"class":238},[232,1640,1641],{"class":306},"\"2\"",[232,1643,260],{"class":238},[232,1645,1620],{"class":316},[232,1647,1593],{"class":238},[232,1649,1650],{"class":306},"\"In Progress\"",[232,1652,1627],{"class":238},[232,1654,1655,1658,1660,1662,1664,1667,1669,1671,1673,1676],{"class":234,"line":356},[232,1656,1657],{"class":316},"    \"priority\"",[232,1659,1607],{"class":238},[232,1661,1610],{"class":316},[232,1663,1593],{"class":238},[232,1665,1666],{"class":306},"\"3\"",[232,1668,260],{"class":238},[232,1670,1620],{"class":316},[232,1672,1593],{"class":238},[232,1674,1675],{"class":306},"\"3 - Moderate\"",[232,1677,1678],{"class":238}," }\n",[232,1680,1681],{"class":234,"line":362},[232,1682,1683],{"class":238},"  }\n",[232,1685,1686],{"class":234,"line":367},[232,1687,1688],{"class":238},"}\n",[12,1690,1691],{},"Then test the failures on purpose:",[38,1693,1694,1704],{},[41,1695,1696],{},[44,1697,1698,1701],{},[47,1699,1700],{},"Test",[47,1702,1703],{},"Expected status",[57,1705,1706,1717,1728,1739,1747,1754],{},[44,1707,1708,1714],{},[62,1709,1710,1711],{},"Path ",[68,1712,1713],{},"\u002Fabc",[62,1715,1716],{},"400",[44,1718,1719,1725],{},[62,1720,1710,1721,1724],{},[68,1722,1723],{},"\u002FINC9999999"," that does not exist",[62,1726,1727],{},"404",[44,1729,1730,1737],{},[62,1731,1732,1733,1736],{},"POST with ",[68,1734,1735],{},"{}"," as the body",[62,1738,1716],{},[44,1740,1741,1744],{},[62,1742,1743],{},"Wrong password",[62,1745,1746],{},"401",[44,1748,1749,1752],{},[62,1750,1751],{},"User without the endpoint role",[62,1753,1212],{},[44,1755,1756,1759],{},[62,1757,1758],{},"User who can read but not write the incident, on POST",[62,1760,1212],{},[12,1762,1763,1764,1767,1768,1771,1772,1774],{},"If a test returns 500, check the system log for the script error. Wrap risky parts of the handler in ",[68,1765,1766],{},"try\u002Fcatch",", log the detail with ",[68,1769,1770],{},"gs.error",", and return a generic ",[68,1773,1198],{}," so callers never see stack traces.",[30,1776,1778],{"id":1777},"step-6-version-it-before-anyone-depends-on-it","Step 6: Version it before anyone depends on it",[12,1780,1781,1782,1785,1786,1789,1790,1793],{},"On the API record, use ",[16,1783,1784],{},"Enable versioning"," before the first consumer goes live. Versioned resources are served at ",[68,1787,1788],{},"\u002Fapi\u002F\u003Cscope>\u002Fincident_api\u002Fv1\u002F...",", and you can add a ",[68,1791,1792],{},"v2"," later without breaking existing callers. Retrofitting versions after consumers hard-code the unversioned path is much harder.",[30,1795,1797],{"id":1796},"checklist-before-you-hand-it-over","Checklist before you hand it over",[184,1799,1800,1803,1806,1813,1824,1827,1833,1840,1843,1846],{},[110,1801,1802],{},"API created in the right scope, captured in an update set",[110,1804,1805],{},"Path and query parameters validated before any query",[110,1807,1808,1809,1812],{},"Query parameter values read as arrays (",[68,1810,1811],{},"[0]",")",[110,1814,1815,1817,1818,133,1821,1823],{},[68,1816,844],{}," or explicit ",[68,1819,1820],{},"canRead",[68,1822,1179],{}," checks",[110,1825,1826],{},"Field allowlist on anything the caller can choose",[110,1828,1829,1830,1832],{},"Errors returned with ",[68,1831,1364],{}," objects, never raw stack traces",[110,1834,1835,133,1837,1839],{},[16,1836,1406],{},[16,1838,1412],{}," selected",[110,1841,1842],{},"A dedicated integration user and a REST_Endpoint ACL",[110,1844,1845],{},"Every failure case tested, not just the happy path",[110,1847,1848],{},"Versioning enabled before the first consumer",[12,1850,1851,1852,1856,1857,1861],{},"When ServiceNow needs to call another system rather than be called, the patterns are different. The ",[24,1853,1855],{"href":1854},"\u002Fblog\u002Fservicenow-outbound-rest-integration-best-practices","outbound REST integration guide"," and the ",[24,1858,1860],{"href":1859},"\u002Fscripts\u002Frest-api-client","REST API client"," script cover that direction.",[1863,1864,1865],"style",{},"html pre.shiki code .sKWpL, html code.shiki .sKWpL{--shiki-default:#24292E;--shiki-dark:#24292E}html pre.shiki code .sCydW, html code.shiki .sCydW{--shiki-default:#D73A49;--shiki-dark:#D73A49}html pre.shiki code .se37E, html code.shiki .se37E{--shiki-default:#6F42C1;--shiki-dark:#6F42C1}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sj_tP, html code.shiki .sj_tP{--shiki-default:#E36209;--shiki-dark:#E36209}html pre.shiki code .sOTlB, html code.shiki .sOTlB{--shiki-default:#032F62;--shiki-dark:#032F62}html pre.shiki code .sMN4m, html code.shiki .sMN4m{--shiki-default:#005CC5;--shiki-dark:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":228,"searchDepth":272,"depth":272,"links":1867},[1868,1869,1870,1871,1872,1873,1874,1875],{"id":32,"depth":272,"text":33},{"id":104,"depth":272,"text":105},{"id":171,"depth":272,"text":172},{"id":889,"depth":272,"text":890},{"id":1391,"depth":272,"text":1392},{"id":1439,"depth":272,"text":1440},{"id":1777,"depth":272,"text":1778},{"id":1796,"depth":272,"text":1797},"2026-11-16","A worked Scripted REST API example in ServiceNow: create the API, add GET and POST resources, read parameters, return errors, secure it, and test with curl.",null,"md",[1881,1884,1887,1890],{"question":1882,"answer":1883},"Where do I create a Scripted REST API in ServiceNow?","Navigate to System Web Services > Scripted Web Services > Scripted REST APIs and select New. The API record is stored in the sys_ws_definition table, and each resource you add to it is stored in sys_ws_operation.",{"question":1885,"answer":1886},"What is the URL of a Scripted REST API?","The base path is \u002Fapi\u002F\u003Cnamespace>\u002F\u003Capi_id>. For a scoped application the namespace is the scope name. Each resource adds its relative path to the base path, so a resource with the path \u002F{number} becomes \u002Fapi\u002F\u003Cnamespace>\u002F\u003Capi_id>\u002F{number}.",{"question":1888,"answer":1889},"Why does request.queryParams.limit return an array?","Each value in request.queryParams is an array of strings, because a query parameter can appear more than once in a URL. Read the first element, for example request.queryParams.limit[0], and convert it to a number yourself.",{"question":1891,"answer":1892},"How do I return a 404 or 400 from a Scripted REST API?","Return one of the error objects in the sn_ws_err namespace, such as new sn_ws_err.NotFoundError('message') or new sn_ws_err.BadRequestError('message'). ServiceNow sets the status code and writes a standard error body. For other codes, use sn_ws_err.ServiceError and call setStatus, setMessage and setDetail.",{},"\u002Fblog\u002Fservicenow-scripted-rest-api-example",{"title":5,"description":1877},"\u002Fsocial-card.png","blog\u002Fservicenow-scripted-rest-api-example",[1899,1900,1901],"scripted rest api","integrations","scripting","GxomPezJBa7rbwTf5QjLa-9uPd9n-jZPcOnuzuvxfZo",[1904,1909,1914],{"path":26,"title":1905,"headline":1906,"description":1907,"date":1908,"tags":1878},"ServiceNow Scripted REST API: 10 Best Practices for Secure, Production-Ready APIs","10 Scripted REST API Best Practices Every ServiceNow Developer Should Know","Build secure, maintainable Scripted REST APIs in ServiceNow with proper authentication, input validation, error handling, pagination, and integration patterns used in production environments.","2026-09-21",{"path":1854,"title":1910,"headline":1911,"description":1912,"date":1913,"tags":1878},"ServiceNow Outbound REST Integrations: 9 Production Best Practices","9 Best Practices for Reliable ServiceNow Outbound REST Integrations","Build reliable ServiceNow outbound REST integrations with secure credentials, timeouts, retries, idempotency, logging, rate-limit handling, and practical testing.","2026-08-13",{"path":1915,"title":1916,"headline":1917,"description":1918,"date":1919,"tags":1920},"\u002Fblog\u002Fcustomizing-oauth2-parameters-servicenow-netsuite","Customizing OAuth2 Parameters in ServiceNow for NetSuite Integration | SN-Tricks","Customizing OAuth2 Parameters in ServiceNow for NetSuite Integration","Learn how to modify OAuth2 request parameters in ServiceNow by extending OAuthUtil for NetSuite and other integrations","2025-07-16T10:00:00",[1921,1922,1923,1924,1925,1926,1927],"ServiceNow","OAuth2","NetSuite","Integration","REST API","Script Include","Authentication",1794791164886]