Exemple d’API REST scriptée - exemples de script

Ces exemples montrent comment créer divers scripts de ressource pour une API REST scriptée.

Exemple d’exemple GET des paramètres de requête

Cet exemple montre comment obtenir des valeurs de paramètre de requête à partir d’une requête.

/**
 * GET - Sample Request API - Query Params
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var uri = request.uri;
    var url = request.url;
    var queryParams = request.queryParams;
    var customHeader = request.getHeader('X-Custom');

    return {
        "uri": uri,
        "url": url,
        "queryParams": queryParams,
        "customHeader": customHeader
    };

})(request, response);

Exemple GET des paramètres de chemin

L’exemple suivant montre comment obtenir les valeurs des paramètres de chemin d’accès à partir d’une requête.

/**
 * GET - Sample Request API - Path Params
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var uri = request.uri;
    var url = request.url;
    var path = request.pathParams;

    return {
        "uri": uri,
        "url": url,
        "path_params": path,
        "path.id": path.id
    };
})(request, response);

Exemple de script include GET

Cet exemple montre comment utiliser un script include pour fournir une réponse. En utilisant un script include, vous pouvez réutiliser le code commun et maintenir la lisibilité dans les scripts de service REST.

/**
 * GET - Sample Request API - Script Include
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var responseObj = global.SampleDataUtil.getSampleJSON();
    return responseObj;
})(request, response);

Exemple de chaîne POST

Cet exemple montre comment analyser un message POST avec un corps de chaîne et envoyer une réponse en fonction de la requête.

/**
 *  POST - Sample Request API - dataString
 *  sample usage:
 *  var requestBody = request.body;
 *  var requestString = requestBody.dataString;
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var requestBody = request.body;
    var requestString = requestBody.dataString;
    return {"requestString": requestString};
})(request, response);

Exemple de POST binaire

Cet exemple montre comment analyser un message POST avec un corps binaire et envoyer une réponse basée sur la requête.

/**
 * POST - Sample Request API - Body
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var body = request.body.data;
    //do any additional processing on the request body, such as inserting a new record.
    return {
        "body.id": body.id
    };
})(request, response);

Exemple d’erreur non acceptable

Cet exemple montre comment réagir en cas d’erreur inacceptable. Utilisez ce type d’erreur lorsque la valeur d’en-tête Accepter la demande n’est pas prise en charge par le service Web.

/**
 * Sample Not Acceptable Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.NotAcceptableError('sample error message'));
})(request, response);

Exemple d’erreur de demande incorrecte

Cet exemple montre comment répondre en cas d’erreur de demande incorrecte. Utilisez ce type d’erreur pour indiquer une erreur dans la syntaxe de la requête.

/**
 * Bad Request Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.BadRequestError('sample error message'));
})(request, response);

Exemple d’erreur de conflit

L’exemple suivant montre comment réagir en cas d’erreur de conflit. Utilisez ce type d’erreur en cas de plusieurs demandes conflictuelles, telles que plusieurs mises à jour du même enregistrement.

/**
 * Error Response: Conflict Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.ConflictError('sample error message'));
})(request, response);

Exemple d’erreur introuvable

Cet exemple montre comment répondre avec une erreur introuvable. Utilisez ce type d’erreur si la ressource demandée n’existe pas ou n’est pas disponible.

/**
 * Error Response: Not Found Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.NotFoundError('sample error message'));
})(request, response);

Exemple d’erreur de type de média non pris en charge

Cet exemple montre comment réagir en cas d’erreur de type de média non pris en charge. Utilisez ce type d’erreur pour indiquer que le type de contenu de la demande n’est pas pris en charge.

/**
 * Error Response: Unsupported Media Type Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    response.setError(new sn_ws_err.UnsupportedMediaTypeError('sample error message'));
})(request, response);

Exemple d’erreur de service

Cet exemple montre comment répondre en cas d’erreur de service générique. L’objet ServiceError vous permet de définir le code d’état, le message et les détails de l’erreur. Utilisez une erreur de service si les types d’erreur prédéfinis ne répondent pas à vos besoins.

/**
 * Error Response: Custom Error Sample
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var myError = new sn_ws_err.ServiceError();
    myError.setStatus(418);
    myError.setMessage("I am a Teapot");
    myError.setDetail("Here are the details about this error");
    response.setError(myError);
})(request, response);

Exemple de script de ressource REST scriptée

Cet exemple de script de ressource d’API REST analyse les name valeurs et id du corps de la demande et renvoie ces valeurs dans la réponse.

/**
 * POST - Sample Request API - Body
 */
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var body = request.body.data,
id0,name0,id1,name1;
name0 = body[0].name; // 'user0'
id0 = body[0].id; // '1234'
name1 = body[1].name; // 'user1'
id1 = body[1].id; // '5678'

return {
"id": id0,
"name": name0,
"id1": id1,
"name1": name1
};
})(request, response);

Demandes

L’API peut accepter les requêtes XML et JSON.

Tableau 1. Demandes

Demande JSON	Demande XML
POST /api/sn_demo_api/v1/example/body HTTP/1.1 Content-Type: application/json Accept: application/json Host: <instance>.service-now.com Connection: close Content-Length: 91 [ { "name": "user0", "id": 1234 }, { "name": "user1", "id": 5678 } ]	POST /api/sn_demo_api/v1/example/body HTTP/1.1 Content-Type: application/xml Accept: application/json Host: <instance>.service-now.com Connection: close Content-Length: 152 <request><entry> <name>user0</name> <id>1234</id> </entry> <entry> <name>user1</name> <id>5678</id> </entry> </request>

Réponses

Les deux demandes spécifient application/json comme valeur d’en-tête Accepter. Cela entraîne l’utilisation du formatage JSON par chaque réponse, même si le type de contenu de la demande est XML.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 04 Aug 2015 15:20:44 GMT
Server: ServiceNow
Connection: close
Set-Cookie: BIGipServerpool_<Instance>=880838154.47166.0000; path=/

{"result":{"id":1234,"id1":5678,"name":"user0","name1":"user1"}}