Working with Related Object
Last updated
Was this helpful?
Last updated
Was this helpful?
While the definition of a Standard or Topic can be helpful in adding value to your system, there is a lot of power in the relationships available in AB Connect. E.g. The Topics covered by a Standard are represented by a relationship between the Standard and one or more Topics. Assets are related to Standards when they are aligned. Standards are related to other Standards (like Peers).
AB Connect exposes these relationships via the data.relationships property. This section explains how to access the power of these relationships.
Some relationships in AB Connect have properties. E.g. Relationships between Assets and Standards have a disposition, prediction score, dates, etc. These properties are represented in the JSON as meta properties on the relationship. AB Connect allows you to address the relationship meta properties for use in either or . When referencing these properties, include meta. as part of the property path. E.g. fields[assets]=alignments.meta.date_created_utc
Resources can have many related objects - sometimes thousands. In order to maintain system performance, AB Connect limits the number of related objects that are returned when requesting a resource. Use paging on the relationship endpoint to retrieve more (or all) of the related objects.
Some relationships have limited cardinality. E.g. a Standard can have zero or one "parent". Other relationships are not limited but commonly have a small set of related entities. E.g. a Standard typically has a handful of Concepts, however in some extreme situations a Standard may have 50 Concepts. To optimize transmissions, AB Connect will return up to the first 25 related objects but if there are more than 25 related objects, AB Connect returns the first 10 relationships with paging URLs. Note that neither the page size (limit) nor the offset can be changed at this point - but can be changed on the relationship endpoint.
Here is an example of a response showing a Standard's related Peers and the paging URLs to retrieve more peer data. To get this data, you might make a call like:
To load the next page of Peers related to the Standard (00003506-B001-11DA-93BA-9A7258581090), follow the next URL:
https://api.abconnect.instructure.com/rest/v4.1/standards/00003506-B001-11DA-93BA-9A7258581090/peers?offset=10&fields[standards]=statement,number
The data available on the relationship endpoints is a conflation between the related object (attributes and relationships) and the relationship properties (meta).
Objects returned on the relationship endpoint do not support accessing their relationships nor including the further related data. For example, when viewing an Asset, you can see the alignments for that Asset, include related aligned Standards and page through the alignments at the relationship endpoint (assets/GUID/alignments). However, when you are viewing the properties of the aligned Standards on the alignment endpoint (assets/GUID/alignments), you can not include peers to those alignments nor can you page the peer standards. If you need to dig deeper into the aligned standards, you must request the data via the Standards endpoint.
The JSON API standard supports an include argument in the query string. The value of the include argument is a comma separated list of relationships on the specified endpoint. If the include statement appears in the query string, the resources returned in the relationships section and named in the statement are included in the response. This helps the caller avoid a second set of calls to retrieve the object details.
Note that it is important that you specify the relationship name in the include statement rather than the object type. For example, when retrieving Standards there are a number of relationships that are available: parent, ancestors, children, derivatives, origins, etc. Most of them are relationships to other Standards. If you asked the system to include "standards", it would not know which set you are actually requesting. You must explicitly request children (for example).
The generic form of the statement is:
For example:
Will return the details of the Standards related to the requested Topic.
If you include a relationship that does not appear in the request as a "relationship" by being included through the fields argument then the include block will be left out of the response.
E.g. https://api.abconnect.instructure.com/rest/v4.1/standards/1F9D5A8A-7053-11DF-8EBF-BE719DFF4B22?include=ancestors will NOT return the ancestors resources because that relationship is not delivered.
E.g. https://api.abconnect.instructure.com/rest/v4.1/standards/1F9D5A8A-7053-11DF-8EBF-BE719DFF4B22?fields[standards]=ancestors&include=ancestors will have the ancestors listed in the relationships and their details in the included block
Sometimes it is convenient to filter the objects that are returned in the relationship. Meta properties on the relationship can always be used in filtering related objects. However, there are some scenarios where it is helpful to filter the related objects on key properties. E.g. one may only be interested in California Standards aligned to an Asset. To implement filtering related objects on all properties presents architectural challenges so to strike a balance and facilitate common use cases, AB Connect allows the caller to filter related object on specific properties on certain relationships.
When filtering on related objects, use the relationship name in the filter statement. E.g.
Will return math Assets and the alignments relationship for each Asset will only include Texas Standards aligned after March 12th 2020.
This section describes properties that can be be used when filtering objects related to the Asset.
When filtering aligned Standards, use the relationship name in the filter statement. E.g.
Supported properties include:
ancestors.id
concepts.context
concepts.descr
disciplines.subjects.descr
disciplines.subjects.guid
document.descr
document.guid
document.publication.descr
document.publication.guid
document.publication.authorities.descr
document.publication.authorities.guid
document.publication.regions.descr
document.publication.regions.guid
education_levels.grades.descr
education_levels.grades.guid
number.raw
number.enhanced
number.prefix_enhanced
section.guid
section.descr
status
statement.descr
topics.descr
Notes:
deleted_alignments are filterable in a similar fashion as alignments.
You can use any of the "meta" properties on the relationship in the filtering - e.g. meta.score, meta.tags, etc. See the relationship definition for a complete list of meta properties.
Only data associated with accepted and predicted Topics are filterable. Filtering on Topics properties will not return any rejected Topics. The only supported property is the Topic description.
Note that the relationship and type of Topics is the same in this instance:
Only data associated with central and relevant Concepts are filterable. Filtering on Concept properties will not return any not_applicable or avoid Concepts. The only supported properties are the Concept description and context.
Note that the relationship and type of Concepts is the same in this instance:
When retrieving Concepts related to a Standard, you can filter the list on context and description.
One common need is to search across object relationships - for example, search for Assets based on properties of related Standards. Since this is a common need, AB Connect supports searching Assets based on key properties of related entities. E.g.
This will return Assets aligned to Standards in California. This can be combined with other properties on the Asset or related entities. E.g. to find Assets related to California Standards on a particular Topic
And combining that with Asset properties...
The text fields on the related entities are also indexed with the Asset full text search. This strengthens the Asset full text search in two ways.
When searching Assets for a key word or phrase, the engine will respond with Assets that are associated with that word or phrase through relationships and not just with the Asset properties.
Full text search results include the text of related entities when ranking results. E.g. If an Asset is related to multiple Concepts, Topics or Standards that contain the word "triangle" it will appear higher in the search results than an Asset that only mentions the word in a text field or has a few related entities that contain "triangle".
The following list shows related entity properties that can be included in an Asset search:
Standards
alignments.ancestors.id
alignments.concepts.context - this field is also included in full text searches once for each Standard that has this Concept in a Key Idea
alignments.concepts.descr - this field is also included in full text searches once for each Standard that has this Concept in a Key Idea
alignments.document.disciplines.subjects.descr
alignments.document.disciplines.subjects.guid
alignments.document.descr - this field is also included in full text searches
alignments.document.guid
alignments.document.publication.descr - this field is also included in full text searches
alignments.document.publication.guid
alignments.document.publication.authorities.descr
alignments.document.publication.authorities.guid
alignments.document.publication.regions.descr
alignments.document.publication.regions.guid
alignments.education_levels.grades.descr
alignments.education_levels.grades.guid
alignments.number.raw
alignments.number.enhanced
alignments.number.prefix_enhanced
alignments.section.guid
alignments.section.descr - this field is also included in full text searches
alignments.status
alignments.statement.descr - this field is also included in full text searches
alignments.topics.descr - this field is also included in full text searches once for each Standard that covers this Topic
Topics - Only data associated with accepted and predicted Topics are searchable on the Asset
topics.descr - this field is also included in full text searches
Concepts - Only data associated with central and relevant Concepts are searchable on the Asset
concepts.context - this field is also included in full text searches
concepts.descr - this field is also included in full text searches
Notes:
Assets can be filtered by deleted_alignments properties in a similar fashion as alignments, however, no deleted_alignments properties are included in an Asset's full text search.
It is also possible to search on the properties of the relationship between Assets and entities with simple relationships to Assets (Standards, Topics, Concepts, etc.). In order to do that, address the relationship properties as if they were properties on the related entity itself. E.g. you can filter on accepted Standards with alignments.meta.disposition eq 'accepted'. To search for Assets that have accepted relationships with a specific standard, your filter statement will look like:
Note that you can use any of the "meta" properties on the relationship in the filtering - e.g. alignments.meta.score, alignments.meta.tags, etc. See the relationship definition for a complete list of meta properties.
Like Assets, Standards can also be filtered by some key properties on related entities. The following list shows related entity properties that can be included in a Standard search:
Concepts
concepts.context - this field is also included in full text searches
concepts.descr - this field is also included in full text searches
To search for resources by properties on related entities other than those listed above, use the search capability to locate the related entities of interest, build a list of related entities and then search the resource by the related entity IDs. For example, if you'd like to find Standards in Virginia that cover Exponents in the 8th grade, first search for the Topic. Topics are grade banded so you'll want to include the grade in your filter to ensure you are getting the correct Topic for the grade.
The result is Topic 06EA4018-32ED-11E0-8DE3-079AD51F4EFC. Then search the Standards for items in Virginia related to this Topic.
If the result of the first search resulted in multiple related Topics (say you also wanted to include Standards related to "Problem Solving"), you can include them all in the Standards filter using the "IN" clause. E.g.
Although we use Standards and their relationships to Topics in this example, the same approach can be taken for searching for any objects based on their relationship to other objects. E.g.
Locating Standards related to Concepts or other Standards
Locating Topics related to Standards or other Topics
Locating Assets related to other Assets or to properties of Standards, Topics or Concepts not listed above.
When searching across relationships and specifying the filter criteria, the filter property name is based on the relationship rather than the related object type. For example, standards is a resource type and the Standards endpoint has relationships with other Standards. However, those relationships are named parent, ancestors, origins, derivatives, children, peers, etc. If the filter referenced the type instead of the relationship name, the filter would read filter[standards]=(standards.id eq 'F97EA8C2-D9AE-11E2-8230-99ABD51F4EFC') and the system would have no way to know which relationship you were filtering on. Instead, if you were looking for Standards that were under a given Standard (i.e. Standards that had a certain Standard as an ancestor) the proper filter notation would be filter[standards]=(ancestors.id eq 'CB411CD4-D90D-11E2-8BD3-EF629DFF4B22').
See for details on working with the relationship endpoints.
The Academic Benchmarks Topics and Concepts are licensed separately. See the section on for a discussion on the licensing required for access to those taxonomies.