What is HATEOAS
One of the core principles of a REST API is being able to navigate resources without needing to know about their location. Hypermedia as the Engine of Application State (HATEOAS) is roughly speaking the inclusion of links and URI’s between resources in your API. Without these links, API consumers would need to know specific resource locations and how to query them.
When using these links, you can query a known API URL as an entry point to the API and then navigate the response links to find other resources in the API. In theory, you only need to know the API's entry point to be able to query it!
How is this relevant to AccountRight Live
In AccountRight Live, we have two entry point URL’s: one for the cloud API and one for the local API. Here we'll refer to the cloud API, but the principles and best practice still apply to the desktop API as well.
The AccountRight Live API entry URL is https://api.myob.com/accountright/
. Making a GET request on this resource will return a list of the company files you have access to. This is determined by the my.myob user who is logged in via OAuth.
For example, you might get a response with one company file:
{ "items": [{ "Id": "d2014f64-ffdf-487b-8d12-67a20976aca6", "Name": "Best Practice Guides", "LibraryPath": "Internal Sandbox API", "ProductVersion": "2015.4", "ProductLevel": { "Code": 20, "Name": "Standard" }, "CheckedOutDate": null, "CheckedOutBy” : null, "Uri": "https://ar3.api.myob.com/accountright/d2014f64-ffdf-487b-8d12-67a20976aca6/", "Country": "AU" }] }
Take a close look at the use of the URI field – this is the link between resources. In this example its a link to the company file.
AccountRightLive Best Practice
In the example above, the Company File called “Best Practice Guides” is located at https://ar3.api.myob.com/accountright/d2014f64-ffdf-487b-8d12-67a20976aca6/
. A further GET request to this endpoint will return a long list of API resources that you’re able to access. Noting of course that you will need to provide the x-myobapi-cftoken
header.
Let's assume for a moment that we want to retrieve a list of employees from this company file. To do this we'd need to do make a GET request to the Contact/Employee endpoint.
The best way to achieve this is to either:
- Combine the Company File URI from the first request with ‘/Contact/Employee’ or
- Use the URI returned from the API when querying the company file endpoint.
In an ideal, best practice implementation you shouldn't need to manually construct any URIs while using the AccountRight Live API.
Why not construct URIs?
If you manually construct URIs, the API can't guide you to the right resource locations. For example, if any API endpoints get added or moved you’ll need to change your code instead of getting the updates provided to you by our API.
In 2014 – alongside the release of v2 – we announced that the API URIs may be changing for company files (you can read the full announcement on our blog ). If endpoints move, your requests might be slower or even time out causing errors.
What changes should I make to my code?
If you’re using the official AccountRight Live .NET SDK, you don’t need to make any changes! We already follow this practice in consuming API URIs.
However if your current code doesn’t work like this, you’ll need to make some changes. Since the AccountRight Live API is centred around CompanyFiles, a great place to start is to store the CompanyFile URI when first querying the API.
Comments
0 comments
Article is closed for comments.