Compose HTTP requests and handle errors

 

Updated: May 9, 2017

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You interact with the Web API by composing and sending HTTPrequests. You need to know how to set the appropriate HTTPheaders and handle any errors included in the response.

To access the Web API you must compose a URL using the components in the following table.

Item

Description

Protocol

The appropriate protocol, either https:// or http://.

Base URL

This is the URL you normally use to open the web application.

  • For Microsoft Dynamics 365 (online): use <tenant name>.crm.dynamics.com.

  • For Internet-facing deployment (IFD): use the appropriate URL for your instance. This will be: <organization name>.<domain name>.

  • For Dynamics 365 (on-premises): use <server name>/<organization name>

Web API path

The path to the web API is /api/data/.

Version

The version is expressed this way: v[Major_version].[Minor_version][PatchVersion]/. Valid versions for this release are:

  • v8.0/ For Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1

  • v8.1/ For Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ For December 2016 update for Dynamics 365 (online and on-premises)

The specific value you use is not important with this release as long as you have applied the corresponding updates or service packs. More information: Version compatibility

Resource

The name of the entity, function, or action you want to use.

The URL you will use will be composed with these parts: Protocol + Base URL + Web API path + Version + Resource.

In this release we have applied a number of additive changes with each update or service pack. When these updates are applied they have added the same capabilities to subsequent minor versions. Because of this, if you can use version 8.2, then versions 8.1 and 8.0 will have the same capabilities. This is possible because all the changes have been additive or bug fixes addressing the items listed in Microsoft Dynamics 365 Web API Limitations. No breaking changes were introduced.

System_CAPS_noteNote

The next major version (v9) introduces capabilities which are only available using that version. Subsequent minor versions may provide additional capabilities which will not be back ported to earlier minor versions. Your code written for v8.x will continue to work in v9.x when you reference v8.2 in the URL you use.

For the v8.x release, use the latest version you can and know that updates or service packs within this major version will not introduce breaking changes. However, this will be different in future releases where you will need to pay more attention to the version of the service you address.

HTTP requests can apply a variety of different methods. When using the web API you will only use the methods listed in the following table.

Method

Usage

GET

Use when retrieving data, including calling functions. The expected Status Code for a successful retrieve is 200 OK.

POST

Use when creating entities or calling actions.

PATCH

Use when updating entities or performing upsert operations.

DELETE

Use when deleting entities or individual properties of entities.

PUT

Use in limited situations to update individual properties of entities. This method isn’t recommended when updating most entities. You’ll use this when updating model entities.

Although the ODataprotocol allows for both JSONand ATOMformat, the web API only supports JSON. Therefore the following headers can be applied.

Every request should include the Acceptheader value of application/json, even when no response body is expected. Any error returned in the response will be returned as JSON. While your code should work even if this header isn’t included, we recommend including it as a best practice

The current ODataversion is 4.0, but future versions may allow for new capabilities. To ensure that there is no ambiguity about the ODataversion that will be applied to your code at that point in the future, you should always include an explicit statement of the current ODataversion and the Maximum version to apply in your code. Use both OData-Versionand OData-MaxVersionheaders set to a value of 4.0.

All HTTP headers should include at least the following headers.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

Every request that includes JSONdata in the request body must include a Content-Typeheader with a value of application/json.

Content-Type: application/json

You can use additional headers to enable specific capabilities.

  • To return data on create ( POST) or update ( PATCH) operations for entities, include the return=representationpreference. When this preference is applied to a POSTrequest, a successful response will have status 201 (Created). For a PATCHrequest, a successful response will have a status 200 (OK). Without this preference applied, both operations will return status 204 (No Content)to reflect that no data is returned in the body of the response by default.

    System_CAPS_noteNote

    This capability was added with December 2016 update for Dynamics 365 (online and on-premises).

  • To return formatted values with a query, include the odata.include-annotationspreference set to Microsoft.Dynamics.CRM.formattedvalueusing the Preferheader. More information: Include formatted values

  • You also use the Preferheader with the odata.maxpagesizeoption to specify how many pages you want to return. More information: Specify the number of entities to return in a page

  • To impersonate another user when the caller has the privileges to do so, add the MSCRMCallerIDheader with the systemuseridvalue of the user to impersonate. More information: Impersonate another user using the Web API.

  • To apply optimistic concurrency, you can apply the If-Matchheader with an Etagvalue. More information: Apply optimistic concurrency.

  • To enable duplicate detection for a POST request, you can use the MSCRM.SuppressDuplicateDetection: falseheader. More information: Check for Duplicate records

  • To control whether an upsert operation should actually create or update an entity, you can also use the If-Matchand If-None-Matchheaders. More information: Upsert an entity.

  • When you execute batch operations, you must apply a number of different headers in the request and with each part sent in the body. More information: Execute batch operations using the Web API.

Whether an http request succeeds or fails, the response will include a status code. Status codes returned by the Microsoft Dynamics 365Web API include the following.

Code

Description

Type

200 OK

Expect this when your operation will return data in the response body.

Success

201 Created

Expect this when your entity POSToperation succeeds and you have specified the return-representationpreference in your request.

System_CAPS_noteNote

This capability was added with December 2016 update for Dynamics 365 (online and on-premises).

Success

204 No Content

Expect this when your operation succeeds but does not return data in the response body.

Success

304 Not Modified

Expect this when testing whether an entity has been modified since it was last retrieved. More information: Conditional retrievals

Redirection

403 Forbidden

Expect this for the following types of errors:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Client Error

401 Unauthorized

Expect this for the following types of errors:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Client Error

413 Payload Too Large

Expect this when the request length is too large.

Client Error

400 BadRequest

Expect this when an argument is invalid.

Client Error

404 Not Found

Expect this when the resource doesn’t exist.

Client Error

405 Method Not Allowed

This error occurs for incorrect method and resource combinations. For example, you can’t use DELETEor PATCHon a collection of entities.

Expect this for the following types of errors:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Client Error

412 Precondition Failed

Expect this for the following types of errors:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Client Error

500 Internal Server Error

Expect this when a POST request to create an entity enables duplicate detection and the entity to create would be a duplicate. More information: Check for Duplicate records

Server Error

501 Not Implemented

Expect this when some requested operation isnt implemented.

Server Error

503 Service Unavailable

Expect this when the web API service isn’t available.

Server Error

Details about errors are included as JSONin the response. Errors will be in this format.

{ "error":{ "code": "
        <This code is not related to the http status code and is frequently empty>", "message": "
        <A message describing the error>", "innererror": { "message": "
        <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
        <Details from the server about where the error occurred>" } } }

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. Copyright

Community Additions

Show: