REST API/Conventions

The following conventions apply to REST requests (data sent to the server), responses (data coming back), and resources (URLs):

• GET requests specify arguments using query parameters.

• GET requests can specify the response format using the alt query parameter. (?alt=json or ?alt=xml)

• POST requests add things. PUT requests update things.

• POST/PUT request format can be either JSON or XML.

The argument format is specified using Content-Type in the http header.

The Content-Type value is either application/xml or application/json

There is no default. The Content-Type must be specified.

Note: For information on usage of special characters when using XML format, see XML

• POST/PUT requests can specify the response format as either JSON or XML by using Accept in the http header.

• The default format for all responses is JSON. (In JavaScript, such data can be easily and efficiently eval'ed into an object.)

• Some browsers (notably Firefox) automatically add an Accept header that specifies an XML response. (When testing behavior in those browsers, you'll see XML coming back, even though the default is JSON. Particularly when testing GET requests.)

• REST API calls typically require either an Object Type Identifier or a Record Id, specified in either the URI and/or XML, in order to specify the type of object and/or the specific record to be acted on.

• Elements (tagnames) in XML requests and responses are listed under the heading, Fields. That usage is historical, deriving from the fact that, in general, each request/response corresponds to a Java Bean used in a Java API call.

• For POST requests, a resourceId is returned, which can be a positive integer or a GUID, depending upon the type of resource created.

• For PUT requests (updates):

• The target object/record is specified in the URI.
• An object or record ID specified in the request is ignored.
• Fields are specified in the request.
• Most fields are optional. (Those that are required are specified in the documentation page for that resource, under Fields.)
• If a field is missing, existing data in that field is unaffected.
• If a field is specified, but empty, any existing data in that field is deleted.

• Fields are specified in a table for each REST API.

• Field data types describe the kind of data that the field contains. The most common data types are:

Boolean	A binary value. The case-insensitive choices are : "true", "false", "yes", "no", "1", or "0".
Currency	A string of digits, including a single decimal point
Date	A date, time, or combination of the two. Format is specified in the "Additional Information" column of the field-specification table.
int	A numeric, integer value.
Number with Decimal	A string of digits, including a single decimal point
List	A list containing homogenous of subelements. If the element name is <things>, then the subelements are generally labeled <thing>.
String	An alphanumeric string value.
Struct	A structure consisting of multiple heterogenous subelements. If the element name is <things>, then subelements might be <car>, <house>, <boat>.

Learn more: Database Format

Query Parameter Arguments

Parameters shown in braces in URIs and REST requests designate arguments you supply. These parameters are typical:

• {yourDomain} - represents the Service Domain (platform hostname or IP address)
• {objectName} - an Object Type Identifier
• {recordId} - a Record identifier
• {viewId} - a View identifier

In each case, you specify the value for your domain, the name of the object your are accessing, etc.

Note: Where {objectName} is required, an {objectId} can also be used. But {objectName} is recommended, because it is always human-readable. (The {objectId} is human-readable for System Objects, but not for Custom Objects.)

Examples:

• https://{yourDomain}/networking/rest/user/{recordId}
• https://{yourDomain}/networking/rest/field/{objectName}/{fieldName}

Dynamic Search Parameters

Search URIs use query parameters like these:

Query Parameters

• fieldList - A comma-separated list of field names to retrieve

• The asterisk (*) wildcard specifies all fields
• {fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

• For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
• For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
• alias.* specifies all fields in the aliased object.

• filter - Filtering criteria to filter the records

• For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

• pageSize - Number of records to retrieve from the result set in order to make a "page".
• page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

• getTotalRecordCount returns the number of total records.
  Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

• sortBy - Field name for primary sort
  Ex: &sortBy=name
• sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
  Ex: &sortOrder=desc
• sortBy2 - Field name for secondary sort
• sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs