API Gateway

The API Gateway is home to IATI’s public APIs. It is the central point from which users and tools can programmatically access IATI’s data services.

developer.iatistandard.org

API Gateway

Date published: 11 January 2022

The API Gateway is home to IATI’s public APIs. It is the central point from which users and tools can programmatically access IATI’s data services.

IATI Gateway APIs

Currently two public API’s are available from the API Gateway:

Users of these APIs are required to register and obtain a free API key before using the API. This step allows the IATI Secretariat to better track how the APIs are being used, and ensure a secure and robust service for all users.

Additional IATI APIs

The IATI API Gateway will be the eventual home for all of IATI's supported public APIs. However, as we make this transition some APIs are still documented and accessed elsewhere:

  • IATI Registry API - Information on every organisation publishing IATI data.
  • Codelist API - Two machine readable ways for people to consume the codelists needed to create and interpret IATI data.

Instructions to obtain IATI Gateway API Keys

  • Navigate to https://developer.iatistandard.org
  • Click “Sign Up”
  • Follow sign up process and confirm your account from an email link
  • Sign In to the API Gateway developer portal (same URL as above)
  • Navigate to Subscriptions > Exploratory - link
    • Enter a Subscription Name (this can be anything you want) in the box
    • Check the box to agree to the Terms of Use
    • Click the Subscribe Button
  • This will give you an API Key for 5 calls/minute up to a maximum of 100 calls/week, with no approval process.
  • If you require a higher rate/quota you need a Full Access subscription:
  • Navigate to Subscriptions > Full Access - link
    • Enter a Subscription Name (this can be anything you want) in the box
    • Check the box to agree to the Terms of Use
    • Click the Subscribe Button

Full Access enables subscribers to have unlimited access to Public IATI APIs with high call rate limits.

Your request will go into a queue where the IATI Secretariat will approve it.

  • Once approved, you’ll be able to use the API Keys provided either from within the API Gateway webpage or your local development tools.

Testing the Validator API

Testing from the API Gateway webpage

  • Go to APIs > IATI Validator V2 > POST validate - link
  • Click the green "Try it" button
  • Once you have an active subscription the “Subscription Key” field should auto-populate
  • Set a body
    • You can either paste a raw string of XML or upload a file from your computer with the “Binary” option
  • Click Send

Testing with local tools:

  • Choose an endpoint: e.g. POST https://api.iatistandard.org/validator/validate
  • Subscription Key:
    • Copy your Primary or Secondary Key from your Profile on the API Gateway webpage
  • Add a Header to your request:
    • Key: Ocp-Apim-Subscription-Key
    • Value: <your key>
  • You can see examples of different language requests format (HTTP, curl, etc.) in the “Try it” feature of the API

Testing the Datastore API

Testing from the API Gateway webpage

  • Go to APIs > IATI Datastore > GET Query - link
  • Click the green "Try it" button
  • Once you have an active subscription the “Subscription Key” field should auto-populate
  • Fill out required parameters:
    • collection - which collection you would like to query
      • activity
      • budget
      • transaction
    • responsetype - type of response
      • select - choose for JSON (flat), CSV, or Solr XML response
      • iati - choose to receive an IATI formatted XML response, only available for the activity collection path
      • iati_json - choose to receive structured JSON format, only available for the activity collection path
    • q - Defines a query using standard query syntax. This parameter is mandatory. E.g. search activity description narratives for NGO: “description_narrative:NGO”
  • Click Send

Testing with local tools:

  • Choose an endpoint: e.g.: GET https://api.iatistandard.org/datastore/activity/select?q=description_narrative:NGO
  • Subscription Key:
    • Copy your Primary or Secondary Key from your Profile on the API Gateway webpage
  • Add a header to your request:
    • Key: Ocp-Apim-Subscription-Key
    • Value: <your key>
  • You can see examples of different language requests format (HTTP, curl, etc.) in the “Try it” feature of the Developer Portal

developer.iatistandard.org