1. Define all major functionality up front
First and foremost, as with any development project, you need to figure out what you want to do. Define what functionality you need in the app that you’re building, as well as all use cases and scenarios where the API will need to be accessed. If you have the time and resources, wireframes can be helpful – especially for ensuring that your app will be easy to use and navigate.
Once you’ve created a comprehensive list of the functionality you need implemented, check the API documentation to ensure that the functionality exists in the API as it currently stands. If any of it isn’t, ask the company who developed the API if they would be willing to add the missing functionality for you. For new functions, you may need to explain why you need these changes and how you will use them. You might also want to make the case that your changes can be useful to other companies too; hopefully they will appreciate the feedback.
For example, you might need the company to fine tune their API endpoints to supply data with different search filters and parameters than it currently provides. Or, your app may need to collect or create new data that needs to be accessible within the API, which may require some endpoints and data structures to be modified in order to accommodate this new information.
2. Pad all time estimates
Padding time estimates is generally a good practice whenever working on a complex development project. API integration projects are inherently more complex because they involve the integration of multiple systems, sometimes with different development teams working in different places.
Be sure to budget extra time for all involved parties, as well as allowing for those times when work on one component might create a bottleneck for forward progress on other parts of the project.
Getting all involved companies on the same page early in the project – and getting the API company to enhance, fix, and upgrade their API as early as possible – will help ensure a smooth integration. It would also be a good idea to warn your client that the project can exceed your estimates if the API has bugs, or if new functionality will be introduced during the integration process.
3. Write complete test cases
In our experience, API projects tend to run more smoothly when complete scenarios and test cases are ironed out in the beginning of the project. Even if just one or two small details are missed during the initial scoping work (such as whether a specific API endpoint can return the ID for a record, for example), the development work can be impacted in a major way later on. This makes a good case for using more of a “waterfall” and “test-driven-design” approach in projects that involve APIs and integrations.
In order to write complete test cases, you need to really think about all of the many, unexpected ways that someone might use your app. Ideally, you should find someone other than the primary developer to do this; the primary developer will have expectations for the way the app is used based on their knowledge of the app’s architecture, which may limit their creativity in developing test cases for surprising things a few people might do given the specific capabilities of your tool or service.
For example, most people use Facebook to keep up to date on their friends’ activities, and of course there should be test cases for those activities. However, there are also people who use Facebook as a free photo backup service or as an event calendar system or to run an online business. Tests for these use cases would need to determine how the system performs when loading a profile consisting exclusively of images, with no “friend” activities populating the activity feed, or with a very large number of private events, or when images need to be tied to events for business sales, etc.
4. Write pseudo-code
It may sound a little crazy, but have your developers write complete “pseudo-code”, for all parts of the app that connect to the API, before writing any real code. Pseudo-code is simply plain English statements that contain all classes and functions, if/else statements, and business logic. Be sure to include all necessary components of typical API transactions (including create, read, update and delete functions).
Writing pseudo-code is generally a faster exercise than writing the real code, and it will help uncover all the details of exactly what the API needs to do – what fields need to be available, how they need to be updated, etc. Most importantly, it will confirm whether the API has the necessary functionality that you will need, and/or what upgrades need to be to made to the API in order to provide the necessary functionality. Your developers can then turn this pseudo-code into real code when they build out the application.
5. Do QA on the API
Now that you have mapped out the functionality of your application and written pseudo-code for it, it’s time to do some QA on the API to ensure that the endpoints that you need work without problems. It’s surprisingly common for even popular, open APIs to have numerous bugs that nobody has yet uncovered or fixed. Run calls to the API that simulate every one of the test cases that you have defined previously, and see if you get back the desired results.
You can test the API using a variety of widely available tools, and a good one is Insomnia REST API Client. You should also use a system like JIRA or GitHub Issues to communicate easily about the issues that you find. When this process begins, open communication about any issues that arise is crucial to efficient progress on the project.
When to Do It
One thing to note is that the above five steps should all be completed before ever writing a line of code. Yes, this is a lot of work – but following the above recommendations first will help to reduce the risk inherent in any API project. API integration and development can hit snags – but with the right precautions, those snags won’t turn into insurmountable roadblocks.
