API documentation
Introduction
CASEI is built on top of a PostgreSQL database with multiple tables that each contain fields and foreign keys. Each endpoint in the API will point to a corresponding table. All the available models and fields can be seen at the bottom of this page.
Requesting a bare table endpoint, such as https://admg.nasa-impact.net/api/campaign will return a list of all the metadata items in the table, in this case, for every campaign in the inventory. Specific objects can be retrieved by adding a known UUID after the table name, and if you don’t know the UUID, string match searching is available for most fields. Further details on all search types as well as example queries can be found below.
Running Full Table Queries
As mentioned above, the most basic query returns the full data from a table. For example https://admg.nasa-impact.net/api/campaign will return a list of all published campaign items in the database.
Below is a contrived example of the results from a campaign query, with … indicating the continuation of additional metadata and additional campaigns. Here you can see abbreviated metadata for two campaigns, OLYMPEX and ACES.
{
"success": True,
"message": ",
"data": [
{
"uuid": "2552174b-213c-4bfc-b36a-632fb16c5ec2",
"short_name": "OLYMPEX",
"long_name": "Olympic Mountains Experiment",
"start_date": "2015-11-01",
"partner_orgs": [
"d6ffd2fa-1230-4971-a0a4-832b27b3a6c1"
],
...
},
{
"uuid": "30ba471c-0844-447a-91fd-b63a2f42b715",
"short_name": "ACES",
"long_name": "Altus Cumulus Electrification Study",
"start_date": "2002-08-02"
"partner_orgs": [],
...
},
...
]
}
String Match Queries
In practice, it is unlikely that you will know the UUID of the Campaign or Partner Org you are interested in. Instead you will probably know the short name, long name, or maybe a keyword from the description.
Because all datatypes are serialized into strings, most fields can be searched using basic string matching. A native datetype becomes the searchable string 2022-01-15.
By default, searches are not case sensitive and use a contain logic. For example, the field value of the yellow clouds will match to the search string cloud.
The following parameters are used when constructing a query.
`search_term` : Contains the actual search string, for example: aces, cloud, 2022-01-05.
`search_type` : Optional parameter with a default value of "plain". Other options include "phrase",
"raw", and "websearch". Each option determines how the search terms are treated.
You can refer to the PostgreSQL docs for detailed information on the differences and syntax.
plain: terms are treated as separate keywords
phrase: terms are treated as a single phrase
raw: formatted search query with terms and operators
websearch: formatted search query, similar to the one used by web search engines.
`search_fields`: Optional parameter that defaults to predefined fields in each model.
It specifies the exact field to be searched, such as "short_name",
"description", or "start_date".
Example Queries
We’ve seen a few examples already above, but in this section we will demonstrate all the common use cases.
Querying an entire table
This query will return metadata for all the campaigns.
Query by UUID
This query will return metadata for the exact campaign specified by UUID.
Query by default search fields
Each table has a list of default search fields, usually short_name, long_name, description, and any other text fields. This query will search all of those fields for the listed term.
Query by specific field
If you know the exact field and want to search it specifically, use the search_fields parameter. Here we are looking for the term “ACES” in the short_name field of any campaign.
Query by specific field list
You can also search by a specific list of fields, just join them with a comma. In this example we are searching for the term ice anywhere in the short_name or description field of any campaign.