The Microsoft Dynamics 365 Web API is a RESTful web service that expands developers’ ability to interact with Dynamics 365 functionality and data using the HTTP protocol. You can access the endpoints and operations using standard GET, POST, PUT, and DELETE HTTP methods. The Web API uses the Open Data Protocol (ODAP), an OASIS standard that outlines how to build and consume RESTful APIs.
How Can I Work with the Microsoft Dynamics 365 Web API?
You can access the Microsoft Dynamics API using the Microsoft Visual Studio C# language or client-side JavaScript. To work with C#, developers will need a copy of the IDE Visual Studio 2015 or a more recent version.
You can find free versions of the tool at the Visual Studio Community site. In addition, you must have an established connection to an on-premises or online version of Microsoft Dynamics 365 and a Microsoft Dynamics 365 Server user account.
Developers must authenticate against the Dynamics 365 server before accessing the resources. There are different authentication methods available depending on your development type involving multiple programmatic steps. If you’re working with Windows-integrated authentication, you only need a valid username and password.
However, an online or IFD deployment requires registering the client application before implementing the OAuth authentication process. That can involve working with Azure Active Directory or Active Directory. If you’re working with C#, Active Directory Authentication Libraries (ADAL) are available that simplify the complexity of performing OAuth authentication.
Here, you can find an example of a simple project that walks you through setting up a Microsoft Dynamics 365 Web API project in Visual Studio. You can find more detailed instructions here if you prefer working with client-side JavaScript.
Examples of Microsoft Dynamics Web API Operations
Below is an overview of operations you can perform with the Microsoft Dynamics API.
Set Up HTTP Requests and Handle Errors
Interactions with the Dynamics Web API occur through HTTP Requests. You must set the appropriate headers and have a way to handle errors that might happen in the response. Start by composing a URL containing the following components:
- Protocol (HTTP or HTTPS)
- Base URL
- Web API path
- Dynamics version
- Resource (entity, function, or action you wish to use)
You can use any of the following methods with your HTTP request:
- GET — Retrieve data
- POST — Create entities or call actions
- PATCH — Update entries or perform insert operations
- DELETE — Remove entities or individual entity properties
- PUT — Update individual entity properties
Web API requests should use the Acceptheader value application/json. Remember that all errors get returned in the JavaScript Object Notation (JSON) format. It’s also a best practice to include the specific ODataversion and Maximum version used in your code.
Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0
All JSONData requests in the body should include a Content-Type header with the value application/json.
Content-Type: application/json
Every successful or failed HTTP response will provide a status code. Below are some common examples.
- 200 OK — Success, Data returned
- 201 Created — Success, POST operation succeeded
- 204 No Content — Success, but no content returned
- 403 Forbidden — Client Error for lack of permissions
- 401 Unauthorized — Client Error for lack of authorization
- 413 Payload — Client Error, request length too large
- 400 — Client Error, Invalid argument
- 404 — Client Error, not found
- 500 — Server Error
Querying the Web API
Below are examples of a request and a response designed to retrieve the name property from three accounts held in Dynamics 365.
Request:
GET [Organization URI]/api/data/v8.2/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v8.2/$metadata#accounts(name)",
"value": [
{
"@odata.etag": "W/\"502000\"",
"name": "Second Coffee (sample)",
"accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
},
{
"@odata.etag": "W/\"502001\"",
"name": "Writeware, Inc. (sample)",
"accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
},
{
"@odata.etag": "W/\"502002\"",
"name": "New Adventures (sample)",
"accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
}
]
}
Dynamics Web API will return a maximum of 5,000 entries per request unless you specify a smaller size. If there are more entries available, you’ll see the @odata.nextLink property returned with the additional results. You will need to issue a new GET request using that property to see the next page of data.
You can specify how many pages you want returned using the following example:
Request:
GET [Organization URI]/api/data/v8.2/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3
Response:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3
{
"@odata.context": "[Organization URI]/api/data/v8.2/$metadata#accounts(name)",
"value": [
{
"@odata.etag": "W/\"401001\"",
"name": "Second Coffee (sample)",
"accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
},
{
"@odata.etag": "W/\"401002\"",
"name": "New Software Company, Inc. (sample)",
"accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
},
{
"@odata.etag": "W/\"401003\"",
"name": "Exciting Company (sample)",
"accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v8.2/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}
Create New Entity in Dynamics Web API
Below is an example of using a POST request to create a new account entry into Dynamics Web API. You must identify the correct property names and types. Look here for more information.
Basic Create Request:
POST [Organization URI]/api/data/v8.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"name": "New Web Account",
"creditonhold": false,
"address1_latitude": 58.639583,
"description": "Describes the new sample account",
"revenue": 10000000,
"accountcategorycode": 3
}
Basic Create Response:
HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)
You can issue a request that returns a status code of 201 for confirmation that the new entity exists in Microsoft Dynamics 365.
Request:
POST [Organization URI]/api/data/v8.2/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation
{
"name": "New Sample Account",
"creditonhold": false,
"address1_latitude": 55.639583,
"description": "Describes the new account that will return a 201 code",
"revenue": 15000000,
"accountcategorycode": 2
}
Response:
HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v8.2/$metadata#accounts/$entity",
"@odata.etag": "W/\"536530\"",
"accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
"accountcategorycode": 2,
"description": "This describes the newly created sample account that returns a 201 status",
"address1_latitude": 55.63958,
"creditonhold": false,
"name": "New Sample Account",
"createdon": "2016-09-28T22:57:53Z",
"revenue": 15000000.0000,
"_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}
Harness the Full Power of Dynamics 365
The Microsoft Dynamics API expands your ability to connect with Dynamics 365 from various applications. Internet eBusiness Solutions can guide you in integrating the platform with other business applications. Contact one of our representatives if you want to expand your use of Dynamics 365.
