Topics

The Topics resource can be used to access the Academic Benchmarks Topic Taxonomy and related metadata. The API provides a simple integration point, eliminates the need to maintain a copy of the taxonomy locally and provides the foundation for additional connected metadata. Use of the API ensures the most current taxonomy is available to your application.

One of the benefits of AB Connect is the ability to navigate relationships between Topics and Standards. Topics can also be related to other Topics by the nature of their position in the hierarchy of the Topic Taxonomy (parent/child). Retrieving related Standards and Topics is done in a similar fashion as attributes, but they are contained in the JSON API relationships response. Note that due to the JSON API standard, only the type and ID are returned in the relationship data. Keep in mind that the JSON API ID is the same as the AB GUID for these entities. If you'd like to retrieve the data of the related Standards or Topics, use the include parameter.

Topics can also be related to Assets. Note that if a Topic is related to an Asset, Standards related to that same Topic automatically become related to the Asset as "predicted" (and vice versa). Relationships between Topics and Assets are managed through the Asset endpoint. See the documentation on the Asset endpoint for details.

All calls against the Topics resource must be implemented as HTTP GET requests, and must include proper Partner Authentication Credentials.

Note that the Academic Benchmarks Topic Taxonomy is licensed separately. If your credentials are correct and you are still receiving a 401 error (or no results), check with AB Support to ensure you are licensed for Topics.

Single Topic

In its simplest form, you are able to retrieve the details of a specific Topic by appending the AB GUID to the path portion of the URL.

Fetching a Topic

get

Path parameters

guidstringRequired

guid of specified topic

Query parameters

partner.idstringRequired

Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.

auth.signaturestringRequired

Signature for the request authorization.

auth.expiresstringRequired

Expiration timestamp for the authorization.

fields[topics]stringOptional

comma separated list of field names

includestringOptional

A comma separated list of resource names that will be returned in the response.

Responses

200

OK

application/json

400

Bad Request

application/json

401

Authentication Error

application/json

404

Entity not found

application/json

get

HTTPcURLJavaScriptPython

GET /rest/v4.1/topics/{guid} HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*

{
  "links": {
    "self": "text"
  },
  "meta": {
    "took": 1
  },
  "data": {
    "type": "text",
    "id": "text",
    "relationships": {
      "parent": {
        "data": {
          "id": "text",
          "type": "text"
        },
        "links": {
          "related": "text"
        }
      },
      "children": {
        "data": [
          {
            "data": {
              "id": "text",
              "type": "text"
            }
          }
        ],
        "links": {
          "related": "text"
        }
      },
      "standards": {
        "links": {
          "last": "text",
          "related": "text",
          "next": "text"
        },
        "data": [
          {
            "id": "text",
            "type": "text"
          }
        ]
      }
    },
    "attributes": {
      "date_modified_utc": "text",
      "disciplines": {
        "subjects": [
          {
            "descr": "text",
            "code": "text",
            "guid": "text"
          }
        ]
      },
      "status": "active",
      "guid": "text",
      "document": {
        "date_modified_utc": "text",
        "guid": "text",
        "revision_year": "text",
        "adopt_year": "text",
        "descr": "text"
      },
      "seq": 1,
      "level": 1,
      "section": {
        "descr": "text",
        "date_modified_utc": "text",
        "seq": 1,
        "guid": "text"
      },
      "uri": "text",
      "descr": "text",
      "education_levels": {
        "grades": [
          {
            "descr": "text",
            "guid": "text",
            "code": "text",
            "seq": 1
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "text",
      "relationships": {
        "related_courses": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "breakout_origins": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "ancestors": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "topics": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "peers": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "breakouts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "crosswalks": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "replaced_by": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "replaces": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "children": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "concepts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "derivatives": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "origins": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "peer_derivatives": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "parent": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "course_standards": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "contexts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "associations": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        }
      },
      "attributes": {
        "seq": 1,
        "captured_by": "text",
        "utilizations": [
          {
            "type": "alignable",
            "guid": "text"
          }
        ],
        "uri": "text",
        "statement": {
          "addendums": [
            {
              "seq": 1,
              "add_context": "Y",
              "descr": "text",
              "position": "before"
            }
          ],
          "combined_descr": "text",
          "descr": "text"
        },
        "level": 1,
        "date_modified_utc": "text",
        "status": "active",
        "legends": [
          {
            "symbol_position": "before",
            "symbol": "text",
            "descr": "text"
          }
        ],
        "standard_type": "organizational",
        "label": "text",
        "disciplines": {
          "strands": [
            {
              "descr": "text",
              "guid": "text"
            }
          ],
          "ece_domains": [
            {
              "guid": "text",
              "code": "text",
              "descr": "text"
            }
          ],
          "subjects": [
            {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          ],
          "genres": [
            {
              "code": "text",
              "guid": "text",
              "descr": "text"
            }
          ]
        },
        "alt_identifiers": [
          {
            "type": "GUID",
            "source": "canonical",
            "id": "text"
          }
        ],
        "date_deleted_utc": "text",
        "in_list": "Y",
        "guid": "text",
        "key_ideas": [
          {
            "guid": "text",
            "concepts": [
              {
                "descr": "text",
                "guid": "text"
              }
            ]
          }
        ],
        "document": {
          "implementation_year": "text",
          "descr": "text",
          "date_modified_utc": "text",
          "source_url": "text",
          "assessment_year": "text",
          "publication": {
            "descr": "text",
            "source_url": "text",
            "extended_descr": "text",
            "regions": [
              {
                "guid": "text",
                "descr": "text",
                "type": "country",
                "code": "text"
              }
            ],
            "authorities": [
              {
                "guid": "text",
                "descr": "text",
                "acronym": "text"
              }
            ],
            "acronym": "text",
            "publication_type": "standard",
            "guid": "text"
          },
          "guid": "text",
          "obsolete_year": "text",
          "disciplines": {
            "primary_subject": {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          },
          "adopt_year": "text",
          "revision_year": "text"
        },
        "deepest": "Y",
        "number": {
          "root_enhanced": "text",
          "enhanced": "text",
          "prefix_enhanced": "text",
          "raw": "text"
        },
        "education_levels": {
          "ece_ages": [
            {
              "guid": "text",
              "descr": "text",
              "seq": 1
            }
          ],
          "grades": [
            {
              "guid": "text",
              "descr": "text",
              "code": "text",
              "seq": 1
            }
          ]
        },
        "section": {
          "guid": "text",
          "seq": 1,
          "date_modified_utc": "text",
          "descr": "text",
          "implementation_year": "text",
          "number": "text",
          "assessment_year": "text",
          "revision_year": "text",
          "label": "text",
          "obsolete_year": "text",
          "adopt_year": "text",
          "disciplines": {
            "primary_subject": {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          }
        },
        "extensions": [
          {
            "type": "reference",
            "guid": "text",
            "descr": "text"
          }
        ],
        "has_list": "text",
        "topic_organizer": "text"
      },
      "id": "text"
    }
  ]
}

Searching for Topics

Using filtering and facets, it is possible to retrieve sets of Topics that match specific criteria. These Topics are returned in an array of Topics objects. See the Introduction for an explanation on filtering and the use of facets. This section covers the specifics of using these parameters with the Topics resource.

Finding Sets of Topics

get

Query parameters

partner.idstringRequired

Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.

auth.signaturestringRequired

Signature for the request authorization.

auth.expiresstringRequired

Expiration timestamp for the authorization.

fields[topics]stringOptional

comma separated list of field names

filter[topics]stringOptional

an ODATA-like query string used to filter

sort[topics]stringOptional

a comma separated list of property names specifying the sort order of the returned results

facetstringOptional

A comma separated list of facet names that you are requesting the options on.

facet_summarystringOptional

A comma separated list of facet names for which you are requesting summary information.

includestringOptional

A comma separated list of resource names that will be returned in the response.

limitnumberOptional

The page size for the response dataset. limit must be 100 or less.

offsetnumberOptional

How far into the dataset you are paging

Responses

200

OK

application/json

400

Bad Request

application/json

401

Authentication Error

application/json

get

HTTPcURLJavaScriptPython

GET /rest/v4.1/topics HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*

{
  "links": {
    "self": "text",
    "first": "text",
    "last": "text",
    "next": "text",
    "prev": "text"
  },
  "meta": {
    "took": 1,
    "limit": 1,
    "count": 1,
    "offset": 1,
    "facets": [
      {
        "count": 1,
        "facet": "text",
        "details": [
          {
            "data": {
              "descr": "text",
              "code": "text",
              "guid": "text"
            },
            "count": 1
          }
        ]
      }
    ]
  },
  "data": [
    {
      "type": "text",
      "id": "text",
      "relationships": {
        "parent": {
          "data": {
            "id": "text",
            "type": "text"
          },
          "links": {
            "related": "text"
          }
        },
        "children": {
          "data": [
            {
              "data": {
                "id": "text",
                "type": "text"
              }
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "standards": {
          "links": {
            "last": "text",
            "related": "text",
            "next": "text"
          },
          "data": [
            {
              "id": "text",
              "type": "text"
            }
          ]
        }
      },
      "attributes": {
        "date_modified_utc": "text",
        "disciplines": {
          "subjects": [
            {
              "descr": "text",
              "code": "text",
              "guid": "text"
            }
          ]
        },
        "status": "active",
        "guid": "text",
        "document": {
          "date_modified_utc": "text",
          "guid": "text",
          "revision_year": "text",
          "adopt_year": "text",
          "descr": "text"
        },
        "seq": 1,
        "level": 1,
        "section": {
          "descr": "text",
          "date_modified_utc": "text",
          "seq": 1,
          "guid": "text"
        },
        "uri": "text",
        "descr": "text",
        "education_levels": {
          "grades": [
            {
              "descr": "text",
              "guid": "text",
              "code": "text",
              "seq": 1
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "text",
      "relationships": {
        "related_courses": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "breakout_origins": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "ancestors": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "topics": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "peers": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "breakouts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "crosswalks": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "replaced_by": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "replaces": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "children": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "concepts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "derivatives": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "origins": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "peer_derivatives": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "parent": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "course_standards": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "contexts": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        },
        "associations": {
          "data": [
            {
              "type": "text",
              "id": "text"
            }
          ],
          "links": {
            "related": "text"
          }
        }
      },
      "attributes": {
        "seq": 1,
        "captured_by": "text",
        "utilizations": [
          {
            "type": "alignable",
            "guid": "text"
          }
        ],
        "uri": "text",
        "statement": {
          "addendums": [
            {
              "seq": 1,
              "add_context": "Y",
              "descr": "text",
              "position": "before"
            }
          ],
          "combined_descr": "text",
          "descr": "text"
        },
        "level": 1,
        "date_modified_utc": "text",
        "status": "active",
        "legends": [
          {
            "symbol_position": "before",
            "symbol": "text",
            "descr": "text"
          }
        ],
        "standard_type": "organizational",
        "label": "text",
        "disciplines": {
          "strands": [
            {
              "descr": "text",
              "guid": "text"
            }
          ],
          "ece_domains": [
            {
              "guid": "text",
              "code": "text",
              "descr": "text"
            }
          ],
          "subjects": [
            {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          ],
          "genres": [
            {
              "code": "text",
              "guid": "text",
              "descr": "text"
            }
          ]
        },
        "alt_identifiers": [
          {
            "type": "GUID",
            "source": "canonical",
            "id": "text"
          }
        ],
        "date_deleted_utc": "text",
        "in_list": "Y",
        "guid": "text",
        "key_ideas": [
          {
            "guid": "text",
            "concepts": [
              {
                "descr": "text",
                "guid": "text"
              }
            ]
          }
        ],
        "document": {
          "implementation_year": "text",
          "descr": "text",
          "date_modified_utc": "text",
          "source_url": "text",
          "assessment_year": "text",
          "publication": {
            "descr": "text",
            "source_url": "text",
            "extended_descr": "text",
            "regions": [
              {
                "guid": "text",
                "descr": "text",
                "type": "country",
                "code": "text"
              }
            ],
            "authorities": [
              {
                "guid": "text",
                "descr": "text",
                "acronym": "text"
              }
            ],
            "acronym": "text",
            "publication_type": "standard",
            "guid": "text"
          },
          "guid": "text",
          "obsolete_year": "text",
          "disciplines": {
            "primary_subject": {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          },
          "adopt_year": "text",
          "revision_year": "text"
        },
        "deepest": "Y",
        "number": {
          "root_enhanced": "text",
          "enhanced": "text",
          "prefix_enhanced": "text",
          "raw": "text"
        },
        "education_levels": {
          "ece_ages": [
            {
              "guid": "text",
              "descr": "text",
              "seq": 1
            }
          ],
          "grades": [
            {
              "guid": "text",
              "descr": "text",
              "code": "text",
              "seq": 1
            }
          ]
        },
        "section": {
          "guid": "text",
          "seq": 1,
          "date_modified_utc": "text",
          "descr": "text",
          "implementation_year": "text",
          "number": "text",
          "assessment_year": "text",
          "revision_year": "text",
          "label": "text",
          "obsolete_year": "text",
          "adopt_year": "text",
          "disciplines": {
            "primary_subject": {
              "code": "text",
              "descr": "text",
              "guid": "text"
            }
          }
        },
        "extensions": [
          {
            "type": "reference",
            "guid": "text",
            "descr": "text"
          }
        ],
        "has_list": "text",
        "topic_organizer": "text"
      },
      "id": "text"
    }
  ]
}