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.

• 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".
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.
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>.

Query Parameter Arguments

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

• {domain} - 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 Built-in or CRM objects, but not for Custom Objects.)

Examples:

• https://{domain}/networking/rest/user/{recordId}
• https://{domain}/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
• Use the REST API:field Resource to get a complete list of fields
• Field lists for database views need to specify the object's alias, as well as the field name.

• 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> 
   ...
   <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

Important: When searching the CRM Objects using the REST API, you need to use the (mostly uppercase) REST versions of the field names when specifying Field Lists and Filter Expressions in the Dynamic Search Parameters. Those field names are returned, as well. For example: OWNERID. When you do an HTTP GET, on the other hand, tags are returned in lowercase, with underscores. For example: owner_id. Those tag names must be specified when doing an HTTP PUT. Those are also the field names you use in the GUI and in the Java APIs. CRM Objects ACCOUNT LEAD CONTACT CONTRACT CASE OPPORTUNITY PRODUCT PRICE BOOK