Characteristics of Programmatic Use of the REST API
When using REST API methods programatically, be aware of the following.
SSL
SSL is required. Do not attempt to invoke the API over a non-secured HTTP channel.
Method Overrides
If your REST client library does not support PUT, PATCH, and DELETE methods, you can include an "X-HTTP-Method-Override" header and use the POST method. For example:
curl -X POST -u admin:admin "http://localhost:9500/rest/v1/sites/test_site" -H"X-HTTP-Method-Override:DELETE"
POST
POST methods that create single entities return a Location header with the path to the new entity. POST methods that create multiple entities do not return the paths to the new entities.
PUT
PUT methods completely update entities. Omitting a property when using a PUT method results either in an error or in setting the entity's property to a null or default value.
GET
Many GET methods have equivalent system (TDV SQL) queries. The Swagger documentation provides examples.
If a GET method lists items, it supports several query parameters:
• The "limit" parameter specifies the number of records to return.
• The "offset" parameter specifies the starting record.
• The "orderBy" parameter returns results in a specific order. It uses SQL syntax.
— Encode the "orderBy" parameter as you would encode a standard URL query string.
— Escape a field name that contains spaces by surrounding the field name with double quotes.
— In a field escaped for spaces, escape a double quote with two double quotes.
— To determine field names for the orderBy clause, refer to Swagger documentation for equivalent system query syntax.
— Use HELP > SYSTEM TABLES to view documentation of columns in those tables.
• Some orderBy examples:
orderBy=City, State, Zip
orderBy=City DESC, State ASC, Zip
orderBy="First Name" ASC, City, Zip ASC