Integrating D365 with external APIs

Background: what is an API?

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. With more growing inclination towards mobile technologies and cloud based operations, more emphasis has been growing towards leveraging JSON APIs, instead of using conventional SOAP based web services and the associated trade-offs. Think of the time when you used to go to individual websites with your credentials eg. Facebook, LinkedIn, Makemytrip, etc.) And you used to browse through various utility sections, tirelessly. Owing to increasing demands in APIs, now you can simply switch to associated webApps from the PlayStore/Apple-Store of your phone, and browse through various sections effortlessly. 

Dynamics 365 for finance and operations throughout its journey till Ax2012, vividly supported usages of SOAP based exchanges through its usages of AIF utilities and other exchanges. AX7/Dynamics 365 has a robust integration capabilities using both SOAP and oData exchanges by leveraging its Entity framework. You can outbound your data easily exposing the oData endpoint to an external system and let them play with your data (of course through proper validation/authorization).

When it comes to consuming external APIs, the story gets tricky as now you need to validate by using a precarious ways of authentication and authorizations, before you set to send/receive actual information. APIs behave in different ways of authentication, and your code must be ready to consider/accommodate accordingly. 

How APIs are linked with modern day world

Imagine you are building an application which allows the end-user to view themselves on a map and then book a taxi nearby (like Uber). Now you need access to certain information to make this application work (such as an accurate map). What do you do? Instead of making a map based application (which requires massive data collection), you search for alternatives and say you stumble upon something called the Google Maps API. This API allows you to access accurate map data at a particular price. PROBLEM SOLVED. You develop your application, use this API and the application gets deployed. You become a Billionaire.

So, based on the above scenario, an API is nothing but an endpoint (like a url) to which you send a request and receive back data.

So, in the above case, UBER makes requests to Google’s servers for map based data through their Gmap API (since Google already has all the map data) and pays a fee for the data.

Hence, in this case, an API is nothing but accessing information stored in databases/datawarehouses of other 3rd parties.(In this case Uber accessing data stored in Google’s databases…)

So, an API is something which eases/enhances your software development.

REST API

Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, called RESTful Web services, provide interoperability between computer systems on the Internet. RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations. Other kinds of Web services, such as SOAP Web services, expose their own arbitrary sets of operations.

As the Internet industry progresses, creating a REST API becomes more concrete with emerging best practices. As RESTful web services don't follow a prescribed standard except for HTTP, it's important to build your RESTful API in accordance with industry best practices to ease development and increase client adoption.

CRUD!

The name REpresentational State Transfer (REST) implies exchanging data. The server acts as a data store, and the client retrieves and stores data. The server transfers object states to the client. The client can update these states too.

Most REST APIs implement CRUD: Create, Retrieve, Update, and Delete.
Generally supported sets of API methods are: GET, POST, DELETE, GET, PATCH, and PUT. These are HTTP methods that correspond to operations.
We can map these operations into CRUD.

• POST—Create
• GET—Retrieve
• PUT / PATCH—Update
• DELETE—Delete

Steps for a successful integration

When you know your business needs, you need to set up a channel with the third party. When you do that the API asks you for your identity. Once granted you can share/receive the information from the endpoint.

Step 1: setting up channel

Here you need to define the URL that you need to access. In general API's are like below, they have server name, paths, etc.

http://<server name>/v1/export/Publisher/Standard_Publisher_Report?format=csv

There are mainly 4 methods involve in API Testing like GET, POST, Delete, and PUT.

• GET- the GET method is used to extract information from the given server using a given URI. While using GET request, it should only extract data and should have no other effect on the data.

• POST- A POST request is used to create a new entity. It can also be used to send data to the server, for example, customer information, file upload, etc. using HTML forms.

• PUT- Create a new entity or update an existing one.

• DELETE- Removes all current representations of the target resource given by a URI.

In D365, you can initialize this by:

System.Net.WebRequestwebReq = System.Net.WebRequest::Create(<URL>);

webReq.set_Method(“POST”); //Alternately you can do a ‘GET’ here

webReq.set_ContentType(‘application/json’); //a RESTful service generally makes use of JSONs

Step 2: Authentication

Authentication vs Authorization

The two functions are often tied together in single solutions – in fact, one of the solutions we’re going to discuss in a moment is a hybrid system of authentication and authorization. As such, and due to their similarities in functional application, it’s quite easy to confuse these two elements.

The easiest way to divide authorization and authentication is to ask: what do they actually prove? In simple terms, Authentication is when an entity proves an identity. In other words, Authentication proves that you are who you say you are. This is akin to having an identification card – an item given by a trusted authority that the requester, such as a police officer, can use as evidence that suggests you are in fact who you say you are.

Authorization is an entirely different concept, though it is certainly closely related. In simple terms, Authorization is when an entity proves a right to access. In other words, Authorization proves you have the right to make a request. When you try to go backstage at a concert or an event, you don’t necessarily have to prove that you are who you say you are – you furnish the ticket, which is de facto proof that you have the right to be where you’re trying to get into.

Generally available options are:

1. Using bearer tokens
2. Credentials(using user IDs and password) – the ‘Basic Auth’ mode
3. Using API key
4. Digest Auth
5. OAuth 1.0
6. OAuth 2.0
7. Hawk Authentication
8. AWS Signature
9. NTLM Authentication

Note on

OAuth authentication

OAuthallows an end user's account information to be used by third-party services, such as Facebook, without exposing the user's password. Generally, OAuth provides to clients a "secure delegated access" to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

API key

The API key is a unique identifier that is used to authenticate requests associated with your project for usage and billing purposes.

Digest Authentication

Hawk is an authentication mechanism, famous because of its replay attack protection.It is a way to prevent users to tamper with request content or to replay the same request multiple times.This is especially useful in games where you don't want users to publish fake scores or if you call costly API's (send SMS, trigger a costly lambda job, etc.).

Digest access authentication is one of the agreed-upon methods a web server can use to negotiate credentials, such as username or password, with a user's web browser. This can be used to confirm the identity of a user before sending sensitive information, such as online banking transaction history. It applies a hash function to the username and password before sending them over the network. In contrast, basic access authentication uses the easily reversible Base64 encoding instead of hashing, making it non-secure unless used in conjunction with TLS.

Berar token

A Bearer Token is an opaque string, not intended to have any meaning to clients using it. Some servers will issue tokens that are a short string of hexadecimal characters, while others may use structured tokens such as JSON Web Tokens.

Define a header

The REST headers and parameters contain a wealth of information that can help you track down issues when you encounter them. HTTP Headers are an important part of the API request and response as they represent the meta-data associated with the API request and response. Headers carry information for:

1. Request and Response Body
2. Request Authorization
3. Response Caching 
4. Response Cookies

In D365 you can define a header as follows:

System.Net.WebHeaderCollection header;

header = webRequest.Headers;

Generally you can pass on a token to a request by:

header.Add(“Authorization”, token); //Where token is a string variable containing the obtained token.

Passing on a JSON body on your request

System.IO.StreamWriter writer = new System.IO.StreamWriter(webRequest.GetRequestStream());

Writer.writerLine(jsonBody);//Where jsonBody is a string based JSON payload you wish to pass on

Writer.Flush();

Writer.Close();

Writer.Dispose();

Obtaining the response

System.Net.WebResponse response = webRequest.getResponse();

StrstrResponse = Response.getResponseStream().ReadToEnd();