In this era of growing popularity of Micro-services in both Startups and big organizations, integration between various services have become of utter importance. Every now and then you will find yourself integrating with 3rd party, in house or payment services. This is so frequent that there are special integration teams in various organizations just to work on this part. So we understand that integrating with an API is of high importance and learning to integrate in the best way is much more important. This is why we present here some of the best API integration tips and guidelines to help you achieve a better and stable API connection.
Why you should read about API Integration Tips:
Although integration looks like a straightforward job because you have integration documents explaining everything clearly but still there is much more to integration than what meets the eye. Today we will look at some of the best API integration tips and guidelines when integrating with any API or 3rd party services. If you are a developer than this is a must to check list.
1. Read the documentation carefully:
This is the first step when starting integration with an API. You must read the documentation at least 2-3 times before starting out the integration. This is one of the most important API integration tips in the lot. Benefits of this exercise are:
- This will help you collect questions if you have so you can get answers before starting which will save you development time.
- Ask the team to provide a best practices document if exists, it will help you implement the best flow.
- Pay close attention to the errors manual.
- Clarify on every field returned in the response and its type.
2. Make sure to handle errors and edge cases:
When you expect response from someone there are for sure going to be error responses and edge cases. You must be able to handle all the documented errors and any other responses as well. For example timeouts, connection errors, empty responses, invalid responses etc.
3. Write proper test cases:
When implementing API’s you can even write test cases to make sure the connection and other parts related to the API connection are working correctly. For most part of the test cases you will not need a real API connection and can mock the response from API using pre-built responses in JSON or XML depending on the way your API communicates.
Writing tests help you to get confidence in your changes. Whenever you do some changes in your communication code the test cases can test the new stuff immediately and make sure nothing from the sibling part is broken.
4. Try to get Best practices and problems faced by current consumers of that API:
Contact your API provider and ask them to give a list of FAQs which their current consumers have done in the past. This will already answer a lot of questions you might have. Also, if allowed ask them to connect you with one of their current partner so that you can gain valuable insights from their implementation.
This basically helps in implementing via the correct direction from the start, instead of implementing something and then coming back to improve it. Some API providers also provide a best practices document. If not provided, ask for it, as it will save you a lot of effort.
Wonder how to keep your Laravel application secured ? Click here.
5. Consider handling timeouts and action taken in such cases:
Another one of the important API integration tips is handling errors generated from timeouts. Every API response is supposed to arrive within a specified time limit. If the response doesn’t arrive in that time it is considered as an error. But this may not mean that the request had no effect on the receptor side. This might mean that depending on the request action was taken on receiver’s end but this action was not acknowledged to the generator of this request.
That’s why the timeout issues become more frustrating for the developers. Due to timeouts you have all sorts of issues like difference in data on both sides, states out of sync, etc. So you must implement special handling for such cases depending on what is provided from your API provider.
One solution can be to generate an email notification in all cases of timeouts to a special team which will manually make sure everything on both sides is okay.
Other solution can be implementing a sync call after a timeout which will sync anything which is not communicated. But then you will have to add something to handle the sync call timeout :-).
Side Note: Keep timeouts for your requests always 10-20% more than specified by your API partner considering network times into account.
6. Implementation should be kept as stateless as possible to support Scaling:
Micro-services mean it may be possible that you implementation which provides your end-user a way of communicating to an API may have been implemented as a micro-service. This means that at some point it may require scaling. If this is the case than you must make your implementation as stateless as possible.
A stateless application is one in which data is not saved between multiple requests. Which means that if first request saves some data in your application, then second request which might need data from response of first request should also be sent to this particular instance. Otherwise there will be no data. This causes an issue while scaling your application horizontally.
Because horizontal scaling will send requests to different instances based on the load on others, in this way your second request might not get data received in first request at all. For this reason you must make the implementation stateless.
- No file based data persistence at any point.
- Use a database application which can be connected by all instances and which is persisted across all instances.
- Make sure at no point your request is dependent on any other sessions data until or unless that data resides in a shared memory.
7. Consider implementing a ESB or messaging queue:
To make communications swift and error free make sure you use a messaging queue. A messaging queue also enables you application to go stateless as all the messages which needs to be sent to other micro-services are immediately dumped in the queue and any duplicate message is ignored.
You can check this link to give you a better picture on how to choose an ESB for your integration -> https://www.infoq.com/articles/ESB-Integration
Laravel just launched one feature called Laravel Horizon which is a queues monitoring dashboard. Check it out.
8. Consider implementing a Scheduler to finish anything which is not done real-time:
You can consider implementing a scheduler for anything which is not done real-time. What you will do is that log a request if it fails due to an error and have a scheduler picking up such logs after a specified interval.
This scheduler will pick this job log and try to finish this job. After this job is finished it will add a message to notify the system that job no. 1 is finished and the system can now carry on the process further from there.
A scheduler will also help you generate notifications and even it can help you build or refresh your dashboard reports.
Check how to stop brute force attacks with PHP easily with this simple script. Take me there.
9. Use tools like Postman:
When you start to implement an API make sure you start with sending raw requests to bare endpoints. This helps you to see the responses quickly without wasting any time. And if you have a raw working request then it becomes easier to generate its counterpart code.
Other benefit is that with raw request there are more chances of you generating errors due to invalid requests. It will help you see the error response beforehand so that you will be ready to handle such errors in your code.
There are many tools in the market available to test raw requests. Postman is one such solution. -> https://www.getpostman.com/
10. Keep it Simple Silly:
At the end the most important factor is to keep your implementation yet one which is stable enough. These API integration tips and guidelines should help you achieve a good start on integrating that new API.
Please leave your comments and let us know your views.
