This tutorial provides a step-by-step guide on how to use the ActivityInfo API to add a record to your database using a tool called Postman.
Understanding APIs: The Restaurant Analogy
Before delving into the technical aspects, let’s use a simple analogy. Picture yourself at a restaurant:
- You (the customer) scan the menu, pick your dish, and tell the waiter.
- The waiter (the API) takes your order to the kitchen (ActivityInfo).
- The chef prepares your meal (processes your request), and the waiter brings it back to you (delivers the response).
In API terms:
- You: The client, such as Postman or a script you are running.
- Menu: The API documentation, showing you what you can request
- Waiter: The API, handling the communication between you and the ActivityInfo server.
- Kitchen: ActivityInfo’s server doing the processing.
- Order: Your request (e.g., to add/edit a record).
- Meal: The response from the API.
The Activity info API acts as a middleman, allowing you to interact with the ActivityInfo server in a structured, standardized way through third-party applications like Postman.
Installing Postman
- Install and Sign in/up
- Postman on your computer (download it here), or use the web version.
- Create a new workspace
- Click on “Workspaces” menu on the top left of your screen.
- Select “Create Workspace”, then “Blank workspace”.
- Give your workspace an appropriate name, such as “ActivityInfo Workspace”.
- Create a new collection
- In your workspace, click the “+” button next to Collections in the top left panel.
- Choose ‘Blank collection’ and name your collection appropriately, such as “ActivityInfo API”.
- Click on “Add a request” and give it a suitable name to get started.
API Token
An API Token is a unique, securely generated string used to authenticate and authorize a user’s access to an API, granting specific permissions without requiring a username and password.
In the restaurant analogy, this would be equivalent to a digital membership card that grants you access to an exclusive restaurant.
- Login to ActivityInfo on your browser and click on your name appearing on the top-right.
- Click on “Account Settings”.
- Click on “API Tokens”, then click on the “+ Add” button.
- Label the token, select the “Read & Write” option and click “Generate”.
- Select ‘Copy to clipboard’.
Preparing the API request
- Change the request method to “Post” and enter the following URL https://www.activityinfo.org/resources/update
- Click on the “Authorization” tab and select “Bearer Token” as the Auth Type.
- Paste the API Token you copied to the clipboard.
The Request Payload Structure
When adding records through the ActivityInfo API, you need to create a JSON payload that represents data using key-value pairs.
- A key is like a label or field name.
- A value is the actual piece of information that you want to store.
Example:
json
"name": "John Doe"
- Key: “name”
- Value: “John Doe”
Example of a form in ActivityInfo: Individuals.
The Individuals form has five fields: Name, Gender, Education Level, Phone number, and Email.
The first step is to ensure that you have the correct Keys that represent the fields in the form. To do this:
- Navigate to your form.
- Click on “Form Settings” in the top-right corner.
- Finally, click on “Export fields”. This will download the form schema in CSV format, which includes the Keys, including the FormId, FieldCodes and FieldIds, required in building the Changes payload.
json
{
"changes": [
{
"formId": "cpy59somejm6gxj29x",
"recordId": "cr1gmuymelgdauyw",
"parentRecordId": null,
"fields": {
"cnnddzfldu43b9p3": "Jim Jones",
"c8fq4pildu43fmd9": "Male",
"cful4ukldu4jze59": "University degree or higher",
"cm8ysgdldu51fo515": "(876) 098-5678",
"c81qrv9ldu51q8d16": "jimjones@activityinfo.org"
}
}
]
}
formId: "cpy59somejm6gxj29x" is the unique ID that identifies the Individuals form. This Id is also appears in the ActivityInfo URL when you open the Individuals form.
recordId: "c2vgrymel6oy1lq" is a unique ID that identifies this record. It follows a specific pattern: it starts with a lowercase letter (a-z) and can contain only lower case letters and numbers (0-9), with a maximum length of 36 characters.
parentRecordId: The ‘null’ value means that this is a top-level record, not a child of another record.
Fields: These are the key-value pairs of the Individual’s details, which are represented by their respective FieldIds or FieldCodes from the ActivityInfo fields export.
json "cnnddzfldu43b9p3": "Jim Jones", "c8fq4pildu43fmd9": "Male", "cful4ukldu4jze59": "University degree or higher", "cm8ysgdldu51fo515": "(876) 098-5678", "c81qrv9ldu51q8d16": "jimjones@activityinfo.org"
* In the case of multiple-selection fields, enter the values in the form of an array.
* Example: A field with multiple selections for languages spoken by an individual
* ```
json
"languages": ["English", "French", "Spanish"]
Sending the API Request
- Go back to Postman and click on the “Body” tab, select the ‘raw’ option and paste the request payload in JSON format. The request payload is constructed in a specific format that will be understood by the ActivityInfo API.
- Double-check all the key-value pairs to ensure they are correct, and then click the "Send" button.
- A successful API request will return a 200 OK status code, and the record should be visible in the ActivityInfo user interface.
Troubleshooting
The API request may fail with the following error codes. Here are a few potential reasons:
- 400 Bad Request: This happens typically when the API request is malformed or missing required parameters. Check if all the fields IDs are correct and if the recordId is in the correct pattern.
- 401 Unauthorized: This error occurs when the server cannot authenticate the API request. Ensure that your API Token is valid and copied correctly.
- 403 Forbidden: This error occurs when the server understood the API request, but the API Token lacks the necessary read & write permissions.
- 404 Not Found: This error is usually caused by an incorrect URL also referred to as API endpoint. Ensure that the API endpoint is correct.