Security

This controller works under the system security rules and constraints.
For more details, refer to the Authentication section

Note

The following guidelines are intended to illustrate the features and features of this Web API controller.

Aliases

This controller can be invoked by other names besides the default one.

This means that, referring to the routing grammar ({schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}) it is possible to use a different fragment for the {controller} component.

Below is the list of these aliases for the fragment {controller}, sorted by suggested preference of use.

Authentication

JWT Token

In order to invoke the REST API, it is necessary to obtain an authentication token via the appropriate service /Auth/Login

For more details, please see the appropriate section of the documentations.

Bearer Authentication

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.

For more details, please see the appropriate section of the documentations.

Identification of the calling application

Some of the REST API functions can only be used if (in addition to proper user authentication) a declaration of the calling application is also performed.

For more details, please see the appropriate section of the documentations.

Errors

The controller actions will generate errors for the following cases:

• Status 400: Badly formed queries e.g. filter parameters that are not correctly encoded
• Status 401: Authentication failures e.g. unrecognised keys
• Status 403: Forbidden. The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
• Status 404: Not found. Unknown resources e.g. data which is not public
• Status 409: Conflict. Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
• Status 500: Server errors e.g. where something has gone

Errors are formatted in JSON

Versioning

It is possible to select the web services version using the {version} token

/api/{version}/{controller}/{details}/{action}/{id}?{querystring}

The token {version} can contain both "exact" values ​​and the special "latest" alias, which identifies the most recent version among those existing in the system.

In general, the use of the special "latest" alias is strongly recommended.

If you want to be particularly "conservative" and adherent to a specific version, specify the name explicitly (eg "v1").

Routing

The system use the following routing syntax, consisting of a sequence of "path-tokens" (the request parameters):

{schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}

The tokens identify respectively:

• {host} -> HOST of the URL
• {version} -> version of web services
• {controller} -> name of the service (controller) you want to invoke
• {details} -> optional detail level of the returned JSON (if applicable)
• {action} -> optional action (method) invoked in the controller
• {id} -> single optional primary key argument (parameter) of the method in the controller, if it so requires
• {querystring} -> additional parameters and possible "modifiers" of the processing and serialization process

OData

The REST APIs are internally based on the Microsoft WebAPI technology, and are largely compliant with the REST specifications, OData v3 and OData v4.

Functions and details related to OData

For more details and specifications regarding the general criteria to adopt when using the OData functions, refer to the basic guide on the topic

Options

The REST API functions implemented in CRM in Cloud include a vast set of options that allow you to adapt the structure and shape of JSON packages according to your needs and preferences.

Unlike the parameters, which are specified in the URL route (through tokens and querystring), the options must instead be passed through the HTTP headers of the request.

As from RFC6648 all the options passed through HTTP headers have in their name the custom prefix "Crm-".

If a certain option is not specified, the system will use the default value specific to the {version} indicated in the URL.

For a complete discussion of options and polymorphic serialization, refer to the general guide on the subject

Swagger

Below you can download the JSON descriptor in Swagger/OpenAPI format

Download Swagger descriptor