How to Use Your Entity APIs

Estimated reading time: 2 min

Structure

To top

This assumes you have created and filled out a taxonomy.

Your Entity API, as well as your Taxonomy API and Data Cleaning API, is automatically created when you initially create a taxonomy. Your Entity API is used to call and display the entity levels (and up) of your taxonomy.

By default your API is private, not publicly visible to others. It is secured using modern best practices and resides on AWS (Amazon Web Services), supporting high up time and reliability.

First, you will notice that there is a unique group of endpoints, GET calls, created for each entity (up to 2 entities are possible). See an example below, of a College Football Team API that has two entities: “University” and “Team Name”.

 

Filter Parameters

To top

Within each GET call, you’ll notice a table containing filter parameters. A filter parameter is used to filter/limit the returns of the Entity API call.

Filter Options

To top

Next to each filter parameter you’ll see up to four options:

  • Value
  • Required
  • Allow Partial Match

Value: this is where you put in the content of your filter, for testing purposes in the API  interface online only. Value for an ID filter will be a number (call the API to see). The Value for a non-ID parameter, e.g. “Conference” above, will be a string, allowing you to filter by the actual name of each taxonomy level.

Required: this is “No” by default. When flipped to “Yes”, it requires something to be entered into the “value” for that respective filter parameter. Note, by default, filter parameters only show his on exact match.

Allow Partial Match: this is “No” by default. When flipped to “Yes”, it allows filtering to happen on a partial match. You will only see Partial Match on non-ID filter parameters (ID-based filter parameters need a number and use exact match, only).

 

API URL Structure

To top

The Entity API is structured just like the Taxonomy API. Here’s an example of a sample API call:

https://api.classr.io/v1/CfKR7tULOb/entity/entityname

CfKR7tULOb: this is the automatically generated hashcode, unique to your account

“entityname”: this is representative of the entity’s name. It is a transformation of your entity’s name: to lowercase and with spaces removed.

When using filter parameters, the following format will show up.

https://api.classr.io/v1/CfKR7tULOb/entity/entityname?entityname=All filter content goes here

 

When is my Entity API created?
The moment you finish your taxonomy process, the API is automatically created.

How long will it take for API calls to show up in my usage count (on your home dashboard)?
Around a minute.

 

Was this article helpful?
Dislike 0
Views: 39