6.2 Application Programming Interfaces (APIs)

Share Download

Why should I do this?

To enable the integration of different software systems, allowing them to work together and share data. Using APIs can be a huge timesaver: instead of having to source data from outside, you can simply tap into the data through a predefined API communication channel. By exploring how APIs are used, you should be able to assess whether your investment needs an API, and which APIs are relevant to your project.

 

How do APIs relate to FAIR?

 

Accessibility: Building an API as a means of access for your final product, or for the dataset that underlies it, means that users can load the data directly to the application they will use for their analysis or presentation, rather than having to download it as a file onto their local device. When users are constrained by their devices’ storage capacities, APIs present an accessible alternative. Similarly, APIs provide means of access for machines, allowing them to query your data as and when they need to.

 

Download this API factsheet for more insights.

Key concept

 

What is an API?

An API is a set of rules and protocols that allows one software application to interact with another. In this context, it can be thought of as the way in which a machine can access data from another machine directly. It defines the methods and data formats that applications can use to communicate with each other. APIs are widely used in various contexts, including web development, mobile app development, cloud computing, and integration of third-party services. They enable developers to build on existing platforms, leverage functionalities provided by other applications, and create more robust and feature-rich software solutions.

 

Suggested approach

1) If you are a Program Officer (PO), you may want to share this page directly with your grantee, so they can act on it.

2) If you are a grantee, ensure you have technical team members involved in this process. While the content is accessible to both technical and non-technical members, technical expertise will be required to make decisions for the investment in this step.

3) If you have not already downloaded ‘Project SIS’ or ‘Waterways’, the illustrative scenarios provide examples on how each theme is navigated. These scenarios are frequently referred to across the content in Step 6 to help you understand how different aspects within a theme are applied.

 

Things to consider for your investment:

Decide on the scope of the use of APIs

• The first assessment is which APIs are relevant to the research project. APIs provide good foundations of data on which the research can draw. An agronomy API typically makes data about landscape, climate, weather, etc. available for use across applications. This can be a huge timesaver if instead of having to source data from outside, you can simply tap into the data through a predefined API communication channel.

   

  Some questions to begin with:

   

  • Is there specific data that you want to access via API for the research?
  • What are the conditions of access?
  • Is the data applicable for the research?

Identify any APIs used to import data

• Look in the API factsheet and explore typical APIs appropriate to the project, such as:

  • Weather data
    • OpenWeatherMap
    • National Oceanic and Atmospheric Administration (NOAA)
  • Soil data
    • USDA Web Soil Survey
    • Global Soil Map
  • Satellite imagery
    • NASA EarthData
    • European Space Agency Copernicus
  • Farm Management Software (FMS)
    • Many FMS offer APIs for data exchange. Check their documentation for details.

Identify any APIs used to export data or reports

• APIs can also be created to make data and results accessible to other users and applications. The data from the project can be exported and accessed from within an external website or application without having to log in to a secondary site.

  Key questions to ask:

  • What data or result does the researcher want to communicate?

  • What are the conditions for this data to be accessed and used?

  • Who would be ideal in sharing the data?

  • Do we need an API for communicating the results? If so, how do we structure it?

Ensure that the APIs are importing and exporting in conformance with the agreed common data model (CDM)

• If we are building an API, we need to ensure that it conforms to our CDM. While it may take considerable resources to design and code an API, it is important that it conforms to the agreed data model. We present a brief summary of key aspects of building an API from scratch below.

   

  • Define the endpoints: Specify the resources (entities) that your API will expose and the actions (CRUD: Create, Read, Update, Delete) that it will support for each resource.
  • Plan data models: Design your API’s data models to map to the corresponding entities and attributes in the CDM. Ensure data types and structures align with the data model’s specifications.
  • Error handling: Define how your API will handle errors and return informative error messages for debugging purposes.
  • Develop code: Use your chosen language and framework to implement the API endpoints and data models you designed.
  • Data validation: Integrate data validation checks to ensure incoming and outgoing data conforms to the CDM’s data types and constraints.
  • Security measures: Implement authentication, authorization, and encryption mechanisms to protect your API from unauthorized access and data breaches.
  • Thorough testing: Conduct rigorous testing to ensure your API functions as intended, handles different scenarios, and adheres to the defined data model.
  • Documentation: Create comprehensive API documentation, including:
    • API endpoints and their functionalities
    • Request and response formats (e.g. JSON, XML) adhering to the ontology’s data model
    • Authentication and authorization procedures
    • Error codes and their meanings

Identify any security constraints around accessing the data via APIs

• Make a list of key users, and list what access they need to the APIs being used. Identify any problems with access and rectify them.

Illustrative scenarios

Overview Project SIS Waterways

Illustrative scenarios

©Gates Archive/Mansi Midha

• Refer to the illustrative scenario that you have downloaded to see how this has been considered.
• Ensure any work notes or decisions taken are being documented, as this would be useful to refer to at later stages, or for someone new joining the team.

Project SIS

Only the specific theme-related content has been highlighted here.

 

1. Data onboarding

 

Visual Crossing has an API, much like other sources of meteorological data used in agricultural science. This API will provide meteorological data for the areas we are interested in as a .csv file. As per the terms of use mentioned above, our use of the API will have certain constraints, though the project is in an advantageous position in this regard, as we will not be requesting data frequently.

 

2. Data products

 

Although the Project SIS data will be held on the SoilScience website, we are considering building an API that can be used by researchers to import data that fits their needs directly into the analysis tools they use.

 

To do so, we will explore APIs in the agronomy sector that fulfil similar roles to SIS. The NRCS web soil survey API might help in this regard.

Waterways

 

Data onboarding

 

APIs will be used to access the satellite data held by TPPs. For our queries, the APIs will respond with data on surface temperatures and vegetation health, as either KML files, shapefiles, or basic CSVs.

 

To ensure the data we get back is limited only to our area of interest – i.e., the area in which WRO operates—we will build and apply a ‘mask’ as part of our API query.

Where can you use APIs?

The theme of APIs can be important at different stages of your project, whether or not you expect that to be the case. To help you incorporate them into your project planning, this section provides suggestions about where you should think about the theme, structured using the stages from the Data Value Chain (DVC).

 

The DVC is a way of viewing the process of running a project from the point of view of the data, thereby identifying how it is onboarded, processed, enriched, analyzed and released in a product. In doing so, the DVC shows the moving parts in project implementations, making it a useful framework regarding the general steps any project working with data takes.

 

 

There are many benefits to data sharing, and this includes the secondary reuse of data for investigating new issues apart from its original purpose.

Learn more