“APIs are used to connect code but why should researchers care?”
The application programming interface or API seems to be everywhere. The idea makes sense..... it allows different programming languages to talk to each other. Great in theory but in practice it seems very complicated. There are different ways to communicate whether it be SOAP, RPC, websockets or REST and it just adds another layer of code to manage. And all of these complications are before you even start to think about managing and hosting your API.
It seems like APIs are for big organisations that want to share data. It's good to know how to use code to access them but building one and hosting it doesn't seem to make sense.
Imagine if users could access your code using any language. APIs give you this, along with a range of other benefits like unlocking the power of cloud computing. APIs are like language packages on steroids. Most programming languages have frameworks to create API servers; R has plumber, Python has a number of options including Django and FastAPI. By mastering an API framework it opens up new opportunities. Here are a few tips on how to start to build an API:
There are a number of different tools that can be used to access an API. Postman provides a good starting point. The tools allow you to experiment with different API concepts, including endpoints, HTTP methods (e,g, the verbs PUT, POST, GET, DELETE), how to format the body of an API call, the different data format in particular JSON and how it relates to other formats that you are more familiar with.
Most API tools will provide code snippets in different languages using different libraries and packages. You can use these code snippets to see how to integrate API calls within your research code.
Try accessing open-source APIs and start to notice which ones work well and which ones are more difficult. Consider how you can authenticate and format the data request and return.
Find out what API frameworks are available in your preferred coding language. Practice building small easy to use APIs that you can run and test on a local host.
Find a working example and use this as a base API and then try making modifications to the inputs, outputs and processing.
An API is an outward looking tool set, eventually you will want to share access to your API with other users. It is important to provide good feedback. Ensure data inputs meet your requirements. Develop a data validation process and ensure that detailed and accurate feedback is provided to the user.
Once you have an API developed find a cloud provider and host it. Hosting your API in the cloud provides a range of benefits, but most importantly it means your code isn't limited by the computing power of your laptop. It also means you don't need to keep your laptop running 24/7 to serve your incoming requests. We have an up coming article deep diving on cloud hosting.
Once hosted invite colleagues and collaborators to pass data in and get their feedback. Does it meet their expectations? Was the feedback helpful? What improvements could be made?
As you start to get the hang of creating an API you realise that it can be an important engagement and impact tool. Unlike code that you run and sits on your local computer an API is designed to allow your code to always be available to anybody.
The models and algorithms that you sit behind an API will inevetibly change. It is important that as the code changes users are able to keep track and know which version they are using and what improvements you have made.
Think of APIs as modules of code, each module can be accessed by anybody and run independently. However, if you start to build a framework that layers your research planning on top of an API framework it becomes a very powerful tool.
Access to the API modules can be controlled through authenticated access. Project team members might access a data collection API that move data into a database to ensure it is standardised. Statisticians, collaborators and reviewers might access a data analysis API that is used to derive insights. Industry funders, partners and collaborators might access an API that can be used deliver insights and impact.
All of these API functions are possible but require a strategic plan for the development, hosting and updating of research derived APIs. Try to explore how you might build a whole of research program using an API framework.
