Specification Version 1.1
Document Version 1.5
The BYU University API Standard is licensed under The Apache License, Version 2.0.
- Note - Unless otherwise specified the URLs contained in this document are for example purposes only. The actual URLs to any UAPI resource can be found here.
- 1.0 Introduction
- 2.0 URLs
- 3.0 Resources
- 3.1 Resource Representation
- 3.2 Representing a Single Resource
- 3.3 Representing a Collection of Resources
- 4.0 HATEOAS Links
- 5.0 Sub-resources, Field_sets, and Contexts
- 6.0 Filters
- 7.0 Search
- 8.0 Meta Data Sets
- 9.0 Files
- 10.0 HTTP POST, PUT, DELETE
- 11.0 Authorization
- 12.0 Errors
- Version History
The University API (UAPI) Specification is intended to bring standardization to consumers and producers of APIs. It presents a standard for URL design, request and response format, and HTTP methods and return codes. The UAPI standard is required for any API designated as part of the University API and recommended for other APIs whenever feasible.
The University has designated a number of common resources as part of the UAPI implementation such as students, employees, and persons. Other resources represent specific constructs useful within a specific business domain. It is recommended where possible to apply the UAPI standard to domain specific APIs. Detailed information for applying the UAPI standard to domain APIs is provided in a separate document.
URLs provide a unique address space for resources within the UAPI. The UAPI specifies a format for URLs to ensure consistency across resources.
A URL that is part of the UAPI implementation will have the following format:
https://api.byu.edu/byuapi/resource[/identifier]
If the resource has sub-resources (e.g. persons have addresses) they are addressed as follows:
https://api.byu.edu/byuapi/<top-level-resource>/<top-level-resource-identifier>/<sub-resource>/<sub-resource-identifier>
The resource portion of the URL represents an entity within the UAPI. For example, the resource "persons" contains data related to a person. The resource https://api.byu.edu/byuapi/persons is the URL for the Persons resource.
Resources that appear first in the URL structure are considered top-level resources.
All resources are written in their plural form. There are a few exceptions where the API represents a single instance of a resource but these are rare.
Resources are "sub-resources" if they are part of a top level resource. For example, addresses are sub-resources of a persons resource because a person has addresses associated with them.
A sub-resource can be addressed as part of the top level resource by adding the name of the sub-resource to the URL. For example,
https://api.byu.edu/byuapi/persons/123456789/addresses
is the URL for the addresses associated with the person identified by the byu_id of 123456789.
If a resource represents a collection of data an item in that resource collection should be addressable by adding its identifier to the URL. For example, the URL https://api.byu.edu/byuapi/persons/123456789 represents the person with the byu_id of 123456789. An HTTP GET to this URL would return the data related to this particular person.
Sub-resources can also have identifiers. The URL for the work address of a person would be https://api.byu.edu/byuapi/persons/123456789/addresses/WRK
Some resources and sub-resources must be identified by using more than one piece of information. This type of identifier is termed a composite identifier. A composite identifier uniquely identifies a resource by using multiple pieces of information. The values in a composite identifier should be separated by a comma.
Composite identifiers should conform to the pattern:
https://api.byu.edu/byuapi/resource/{key}[,{additional_keys}]
An example of a URL using a composite identifier is:
https://api.byu.edu/byuapi/classes/2016Fall,MATH,110,001
Resources have properties associated with them. Some properties are simple name / value pairs and others may be complex objects. Sub-resources are an example of complex objects that are properties of a top-level resource.
When a consumer of an API interacts with a resource the representation of the properties of that resource is dependent upon the mime-type used. All text based resources will be represented as JSON using the application/json mime-type. Other text representations (XML, etc) can be provided if the API is capable. The HTTP Accept header should be included in the request to indicate to the API which representation(s) the consumer is capable of processing and the HTTP Content-Type header should be included in the response indicating the mime-type of the data being represented. Binary resource properties such as images should use the appropriate mime-type for the type of data being represented.
Single resources are addressed by URLs that end in identifiers (e.g. https://api.byu.edu/byuapi/persons/123456789).
The resource should always include the following elements:
- Links
- Metadata
- One or more sub-resources represented as field_sets (see 5.1 field_sets).
Top level resources should return a default set of properties when no sub-resources have been requested. These properties should be included in a single JSON object with the name basic. See 5.1.3 The Basic Field_set for more information.
Multiple sub-resources can be requested in a single HTTP request. See 5.0 Sub-resources, Field_sets, And Contexts for more information.
The links property is an object that represents possible future actions that can be performed against this resource. The contents of the links section may vary depending upon the context in which the resource is being accessed (date, user authorizations, etc) See 4.0 HATEOAS Links for a more complete discussion of HATEOS links and their purpose.
The metadata property contains data about the request for this resource including any errors the request has generated. In the case of a request that returns a single resource the metadata may include the following:
| Property | Required | Description |
|---|---|---|
| validation_response | yes | This is an object that contains two required properties: code and message. |
| validation_information | no | This is an array of strings that provide information about errors correlated to the validation_response.code and HTTP response code. See 10.0 HTTP POST, PUT, DELETE for more information. |
| validation_identifiers | no | This is a JSON object containing the identifers for this resource. This should be returned if the resource is part of a collection being returned. See 12.2.3 validation_identifiers for more information. |
| cache | required if the result is a cached value | This is an object that contains one required property: date_time. The date_time value is when the data was updated in the cache. |
| restricted | Required if the resource deals with an individual | Indicates that the resource represents a person that has requested that their records be restricted. Special rules apply to restricted resources. See 11.6 - Restricted Resources for more information. |
Metadata related to field_sets and contexts along with any custom metadata about the resource may also be included.
The following metadata object would indicate a successful request for this resource:
"metadata": {
"restricted" : false,
"validation_response": {
"code": 200,
"message": "Success"
}
}The following metadata would indicate an error occurred when processing the request:
"metadata": {
"restricted" : false,
"validation_response": {
"code": 403,
"message": "Not Authorized"
},
"validation_information": [
"Not authorized"
]
}See 12.0 Errors for more information on error handling.
Resource properties contain information about the state of a resource. The persons resource has properties such as byu_id, net_id, preferred name, etc. Property values are returned in a UAPI specific format that provides additional information for the consumer about the property. The The UAPI format is a JSON object that has the following elements:
| Element | Required | Description |
|---|---|---|
| value | value_array | object | object_array | One and only one is required | Contains the data value to be processed. See individual sections for a definition of the possible representations. |
| api_type | Yes | Describes how this value may be used in this API. For a list of the possible values for api_type and the rules associated with each value see the list below. |
| key | Required if the property is the identifier or one of the composite identifiers of the resource. | Designates that the property is one of the key elements for this resource. Key fields are required to have values - they are not allowed to be blank or null. |
| description | No | Explains the data value in human-friendly terms. Should be limited to 30 characters. |
| long_description | No | Explains the data value in human-friendly terms; contains more information than the (short) description. Should be limited to 256 characters. |
| display_label | No | Provides a suggested string to use when creating a label for this property in the user interface. Should be limited to 30 characters. |
| domain | Required if the value property is part of a set of allowable values. | Contains the URL that can be used to retrieve the set of allowable values. The result of invoking the URL could be used to populate the UI's. For example the value "domain": "https://api.byu.edu/byuapi/meta/classes/year_terms" may return a set of the valid year terms. See 8.0 Meta Data Sets for more information. |
| related_resource | Required if the api_type property is related. |
If the api_type is related this property will contain the resource-name that "owns" this property. The resource-name can be used to find a HATEOAS link that can access this property. |
The api_type field is required for all properties. It indicates more information about the value being returned such as if it is modifiable by the consumer, a derived field, a system generated value, etc.
The possible values for api_type are:
| api_type | Modifiable by the consumer through this API | Description |
|---|---|---|
| read-only | No | There are either business rules or authorization considerations that do not allow the property to be changed at this time by the consumer. |
| modifiable | Yes | The property may be modified by the consumer. |
| system | No | The value was assigned by the system. A date-time field that tracks the last time the resource was updated is a good example of a system data value. |
| derived | No | The property was derived by a "calculation" on other properties. An example might be GPA. |
| unauthorized | No | The consumer is not authorized to retrieve this property. This api_type is deprecated. It should not be used for ANY new development. See 11.0 Authorization for more information. |
| related | No | The responsibility for manipulating this property doesn't belong to this API. The business logic to modify the property exists in the related_resource. |
Property values can be expressed as either singleton scalar values, arrays of scalar values, complex objects, or arrays of complex objects.
The value element is used to represent a single scalar as the value of the property. The value returned can be null if the data type of the property supports it.
A property with a single scalar value would look something like this:
"byu_id": {
"api_type": "system",
"display_label": "BYU ID",
"key": true,
"value": "123456789",
"description": "Joe Student"
},Date and Date/Time data types should be represented as strings using the RFC-3339 format. It is suggested that UTC be used instead of local time zones.
The value_array element is used to represent an array of scalar values as the value of the property. The array is represented as a JSON array. The elements for the property are divided between those that apply to the property as a whole and those that are specific to the entries in the array. The value_array element cannot be null. If the array has no elements the array an empty array should be returned.
| Element | Applies to Property or Array Entry | Note |
|---|---|---|
| api_type | Property | |
| display_label | Property | |
| description | Entry | The description of the individual entry in the array. |
| long_description | Entry | |
| domain | Property | |
| related_resource | Both | If applied to the property the URL represents the resource to use to interact with the entire array. If applied to the entry the URL should contain the reference to this specific entry in the array. |
| key | Not Allowed | Arrays cannot be part of the primary key of a resource. |
"instructor_byu_ids": {
"api_type": "related",
"display_label": "Instructors",
"related_resource": "https://api.byu.edu/classes/20185,cs142,1",
"value_array": [
{
"value": "123456789",
"description": "Joe Instructor",
"api_type": "related",
"related_resource": "https://api.byu.edu/persons/123456789"
},
{
"value": "987654321",
"description": "Jane Instructor",
"api_type": "related",
"related_resource": "https://api.byu.edu/persons/987654321"
}
]
}The object element is used to represent a single complex JSON object as the value of the property. The object is represented in standard UAPI specification format as described in 3.2.3 Properties. Only certain elements are valid for a property that contains an object. The object element can be null.
| Element | Note |
|---|---|
| api_type | Must be either read_only or related. |
| display_label | May be used to indicate a display_label for the entire object. |
| related_resource | If applied to the property the URL represents the resource to use to interact with the object as a whole. |
An example of an property containing an object is as follows:
"final_exam_schedule": {
"object": {
"building": {
"value": "RB",
"description": "Richards Building",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1",
"domain": "https://api.byu.edu/byuapi/meta/classes/buildings"
},
"room": {
"value": "164",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
},
"days": {
"value": "S",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
},
"start_time": {
"value": "11:00",
"api_type": "related",
"description": "11:00am",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
},
"end_time": {
"value": "14:00",
"api_type": "related",
"description": "2:00pm",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
},
"start_date": {
"value": "2018-12-15",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
},
"end_date": {
"value": "2018-12-15",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/FINAL%20EXAM,1"
}
},
"api_type": "read-only"
},The object_array element is used to represent an array of complex JSON objects as the value of the property. The objects are represented in standard UAPI specification format as described in 3.2.3 Properties. Only certain elements are valid for a property that contains an array of objects. An object_array element cannot be null. If there are no objects to in the array then an empty array should be returned.
| Element | Note |
|---|---|
| api_type | Must be either read-only or related. |
| display_label | May be used to indicate a display_label for the entire array of objects. |
| related_resource | If applied to the property the URL represents the resource to use to interact with the object array as a whole. |
An example of an property containing an array of objects is as follows:
"when_taught": {
"object_array": [
{
"building": {
"value": "RB",
"description": "Richards Building",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,3",
"domain": "https://api.byu.edu/byuapi/meta/classes/buildings"
},
"room": {
"value": "206",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,3"
},
"days": {
"value": "MW",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,3"
},
"start_time": {
"value": "12:00",
"api_type": "related",
"description": "12:00pm",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,3"
},
"end_time": {
"value": "12:50",
"api_type": "related",
"description": "12:50pm",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,3"
},
},
{
"building": {
"value": "RB",
"description": "Richards Building",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,2",
"domain": "https://api.byu.edu/byuapi/meta/classes/buildings"
},
"room": {
"value": "164",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,2"
},
"days": {
"value": "F",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,2"
},
"start_time": {
"value": "12:00",
"api_type": "related",
"description": "12:00pm",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,2"
},
"end_time": {
"value": "12:50",
"api_type": "related",
"description": "12:50pm",
"related_resource": "https://api.byu.edu/byuapi/classes/v2/Fall2018,C%20S,301R,003/assigned_schedules/CLS,2"
},
}
],
"api_type": "read-only"
},
While the UAPI specification supports complex objects (value_array, object, and object_array) they should be used judiciously. There are a number of implications to using complex objects including:
- Lack of addressability - Complex objects cannot be addressed directly the same way sub-resources can.
- Lack of selectability - Complex objects are always included in the field_set that contains them, unlike field_sets in general which can be included at the discretion of the consumer.
- Data classification issues - Like field_sets, complex objects inherit the classification of the most restricted property they contain. This classification expands to include the entire field_set that contains the complex object.
Single value sub-resources (i.e. those retrieved by using an identifier in the URL) are represented much the same way the basic object is represented. They require the same links, metadata, and properties elements. All properties are represented just under the root of the returned object (i.e. they do not have a basic object).
A single top level resource representation would look like:
{
"links":...,
"metadata":...,
"basic": {
"links": {
"persons__info": {
"rel": "self",
"href": "https://api.byu.edu/byuapi/persons/123456789",
"method": "GET"
},
"students__info": {
"rel": "students__info",
"href": "https://api.byu.edu/byuapi/students/123456789",
"method": "GET"
}
},
"metadata": {
"restricted" : false,
"validation_response": {
"code": 200,
"message": "Successful"
}
},
"byu_id": {
"value": "123456789",
"api_type": "system",
"key": true
},
"person_id": {
"value": "987654321",
"api_type": "system"
},
"net_id": {
"value": "joe",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/persons/123456789/credentials/NET_ID,joe"
},
"personal_email_address": {
"value": "joe@byu.edu",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/persons/123456789/email_addresses/PERSONAL"
},
"primary_phone_number": {
"value": "",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/persons/123456789/phones"
},
"date_time_updated": {
"value": "2016-09-21T09:03:18.000Z",
"api_type": "system"
},
"updated_by_id": {
"value": "323232323",
"description": "Joe Admin",
"api_type": "system"
},
"date_time_created": {
"value": "1997-02-07T12:22:32.000Z",
"api_type": "system"
}
}
}A single sub-resource representation would look like:
{
"links": {
"group_memberships__info": {
"rel": "self",
"href": "https://api.byu.edu/byuapi/persons/123456789/group_memberships/ADMINISTRATIVE",
"method": "GET"
},
"group_memberships__modify": {
"rel": "group_memberships__modify",
"href": "https://api.byu.edu/byuapi/persons/123456789/group_memberships/ADMINISTRATIVE",
"method": "PUT"
},
"group_memberships__delete": {
"rel": "group_memberships__delete",
"href": "https://api.byu.edu/byuapi/persons/123456789/group_memberships/ADMINISTRATIVE",
"method": "DELETE"
}
},
"metadata": {
"restricted" : false,
"validation_response": {
"code": 200,
"message": "Success"
},
"validation_information": [
"No additional information"
]
},
"group_id": {
"value": "ADMINISTRATIVE",
"description": "Administrative",
"api_type": "read-only",
"key": true
},
"group_type": {
"value": "A",
"api_type": "read-only"
},
"byu_id": {
"value": "123456789",
"description": "Joe Admin",
"api_type": "system",
"key": true
},
"department": {
"value": "OIT- Administration",
"api_type": "related",
"related_resource": "https://api.byu.edu/byuapi/employees",
"domain": "https://api.byu.edu/byuapi/meta/employees/departments"
}
}If a UAPI resource (top level or sub-resource) is accessed with no identifier or via a filter or search (see 6.0 Filters and 7.0 Search) a collection of individual resource representations is returned. This collection will have its own set of links and metadata with values that pertain to the collection. The individual resource representations as defined in 3.1 Resource Representation are returned in a JSON array named values.
The links object for a collection will contain HATEOAS links related to processing the collection. They may include links for paging, etc.
The metadata associated with collections includes data about the collection that has been returned.
Metadata related to field_sets and contexts along with any custom metadata about the resource collection may also be included.
| Property | Required | Description |
|---|---|---|
| validation_response | yes | This is an object that contains two required properties: code and message. |
| validation_information | no | This is an array of strings that provide information about errors correlated to the validation_response.code and HTTP response code. |
| cache | required if the result is a cached value | This is an object that contains one required property: date_time. The date_time value is when the data was updated in the cache. |
| restricted | Required for sub-resource collections that deal with individuals. Not required for top level resource collections. | Indicates that the sub-resource represents some aspect of a person that has requested that their records be restricted. See 11.6 - Restricted Resources for more information. |
| collection_size | recommended | The number of items of the resource which exist in the entire collection. Can be omitted if the size is unknown or acquiring the number id computationally intensive. |
The metadata returned for a resource collection would look like:
"metadata": {
"restricted": false,
"validation_response": {
"code": 200,
"message": "Success"
},
"collection_size": 150
}The values array contains an entry for each individual resource representation. The representations must follow the specification in 3.1 Resource Representation including containing the links and metadata properties.
An API can optionally support the ability for a consumer to request the results in a collection be returned in a specific order. Results of the request will be sorted before applying any subset parameters specified in the request (see 3.3.5 Large Collections).
The following metadata properties are required if sorting is supported by the resource:
| Property | Description |
|---|---|
| sort_properties_available | The properties that can be used in requesting a specific order of the collection results. |
| sort_properties_default | The default properties used to sort the collection. |
| sort_order_default | The default sort order used to sort the collection. |
Sort metadata would look like the following:
"metadata": {
"sort_properties_available": [
"byu_id",
"net_id",
"sort_name"
],
"sort_properties_default": [
"sort_name",
"net_id"
],
"sort_order_default": "ascending"
},The query parameters used to specify sort preferences are as follows:
| Parameter | Description |
|---|---|
| sort_properties | Sort the result by the properties listed. Multiple properties may be listed (comma separated). If a property is listed that does not appear in the sort_properties_available metadata property a 400 Bad Request HTTP status code should be returned for the request. |
| sort_order | Specify the order for the sort, either ascending or descending. Only a single order can be specified. The default is ascending. |
Some resources and sub-resources represent a large number of instances. APIs that support large numbers of instances should implement subsets in order to provide the consumer a way to move through the collection in a reasonable way. The consumer should be aware that it may be possible that the underlying data has changed between invocations so instances may be repeated or skipped.
To implement subsets a resource must include specific metadata and links with the collection in the response.
Specifying the start and size of the next subset of results is done via metadata properties. Consumers can specify an offset from the beginning of the collection or the primary key of the instance to start with.
The following metadata properties are required if subsets are supported by the resource:
| Property | Description |
|---|---|
| default_subset_size | Unless overridden in query parameters, this endpoint will return this number of resources in each subset. |
| max_subset_size | The largest number of resources this API can return in one subset. |
| subset_start | The offset (zero based) from the beginning of the collection of the first instance in this subset. |
| subset_size | The number of instances in this subset. |
The metadata returned for a resource collection that supports subsets would look like:
"metadata": {
"restricted": false,
"validation_response": {
"code": 200,
"message": "Success"
},
"collection_size": 150,
"default_subset_size": 50,
"max_subset_size": 1000,
"subset_size": 50,
"subset_start": 51
}In order to implement subsets the following query string parameters are used:
| Parameter | Description |
|---|---|
| subset_start_offset | The offset for the first resource in the collection to be returned in this subset. |
| subset_size | The number of resources in the collection to return (defaults to the value of max_subset_size). |
| subset_start_key | The primary key of the resource to start the subset with. Optional alternative to subset_start_offset. |
If both subset_start_offset and subset_start_key are specified in the same query string a 400 Bad Request should be returned for the entire request.
Additional links are included that provide the link to use in order to move within the collection:
| Link | Content |
|---|---|
| resource-name__info | Link to retrieve this collection - see 4.0 HATEOAS Links |
| resource-name__first | Link to the first subset of the collection |
| resource-name__current | Link to the current subset in the collection |
| resource-name__last | Link to the last subset of the collection |
| resource-name__previous | Link to the previous subset in the collection |
| resource-name__next | Link to the next subset in the collection |
An example of the subset links for the persons resource would be as follows:
"persons__info": {
"rel": "self",
"href": "https://api.byu.edu/byuapi/persons/",
"method": "GET"
},
"persons__first": {
"rel": "persons__first",
"href": "https://api.byu.edu/byuapi/persons/?subset_start=0,subset_size=100",
"method": "GET"
},
"persons__last": {
"rel": "persons__last",
"href": "https://api.byu.edu/byuapi/persons/?subset_start=345600,subset_size=100",
"method": "GET"
},
"persons__current": {
"rel": "persons__current",
"href": "https://api.byu.edu/byuapi/persons/?subset_start=300,subset_size=100",
"method": "GET"
},
"persons__next": {
"rel": "person__next",
"href": "https://api.byu.edu/byuapi/persons/?subset_start=400,subset_size=100",
"method": "GET"
},
"persons__previous": {
"rel": "persons__previous",
"href": "https://api.byu.edu/byuapi/persons/?subset_start=200,subset_size=100",
"method": "GET"
},If the collection returned is empty (e.g. no resources matched a filter) the collection metadata should still be returned. If subsets are supported subset data should still be valid - subset_start should be 0, subset_size should also be 0 since no values were returned. The values array should be empty.
Hypertext As The Engine Of Application State (HATEOAS) is one of the fundamental design considerations of a REST based API. HATEOAS uses hypertext links to provide the consumers of an API with information regarding the next allowable operations the consumer is allowed to perform.
HATEOAS links are intended to convey to the consumer the next possible actions that can be performed on a resource or collection of resources. In the case of a collection of resources the links property may include links for retrieving the first, next, and last resources in the collection and adding a new value into the collection along with paging through the collection. For a single resource the links property may include links to modify or delete the resource along with a link to retrieve this specific resource (useful if the resource is returned as part of a collection). Links should only be provided if the consumer is allowed to perform the specific action represented by the link. For example if the consumer is allowed to modify but not delete the current person resource the persons__modify link will be present in the links property while the persons__delete will not. This way the consumer does not need to understand the business logic behind authorization, it can assume an operation is possible by the presence of the corresponding link.
The UAPI standard varies from traditional HATEOAS implementations in order to make things easier for consumers to utilize the links property. HATEOAS links in the UAPI have the following format:
"persons__info": {
"rel": "self",
"href": "https://api.byu.edu/byuapi/persons/123456789",
"method": "GET"
},The name each of link object and the rel property follows the defined pattern resource-name__business-action. Business actions should convey operations that make sense within the business domain. Consumers can use the name of the links to determine which operations can be performed on the resource.
The properties of the link are defined as follows:
| Property | Description |
|---|---|
| rel | The rel property defines the relationship the link has relative to the resource. The UAPI specification requires the value of rel either be self or match the name of the HATEOAS link object name. self is a special value for rel that indicates this link can be used to retrieve the current resource. |
| href | The href contains the URL used to perform the HATEOAS link action (this may also be a templated URL according to RFC 6570). |
| method | The method contains the HTTP method used when invoking the URL in the href property. |
The UAPI specification requires a self link be included. This link should be the link that can be used to retrieve this specific resource (or collection). For a top-level resource it should be named resource-name__info. If the link is for a portion of the result (such as a sub-resource) it should be named sub-resource-name__info.
An example links object for the person resource at https://api.byu.edu/byuapi/persons/123456789 would look something like:
"links": {
"basic__info": {
"rel": "self",
"href": "https://api.byu.edu/byuapi/persons/123456789",
"method": "GET"
},
"basic__modify": {
"rel": "basic__modify",
"href": "https://api.byu.edu/byuapi/persons/123456789",
"method": "PUT"
},
"basic__delete": {
"rel": "basic__delete",
"href": "https://api.byu.edu/byuapi/persons/123456789",
"method": "DELETE"
}Access to individual sub-resources is accomplished by adding the desired sub-resource name and an optional identifier to the URL of the top level resource. There are cases where access to more than one sub-resource in a single request is necessary or desirable. The UAPI standard provides two query string parameters to this possible: field_sets and contexts.
Field_sets are merely a convenient way to request and represent multiple sub-resources in a single request to a top level resource. The names of field_sets and sub-resources must be the same. If an API supports sub-resources it must also support field_sets.
The API should document the field_sets supported in the metadata of the top level resource. The metadata properties are:
| Property | Required | Description |
|---|---|---|
| field_sets_returned | only if specific field_sets have been requested | JSON array of all the field_sets represented in this result. May be different from the list of field_sets requested in the query string. |
| field_sets_available | only if field_sets are supported | JSON array of all available field_sets available to request for this resource. A consumer may not have access to all field_sets in this array. |
| field_sets_default | only if field_sets are supported | The field_sets that will be returned if no field_sets query parameter is specified. |
Example metadata from a top-level resource that supports field_sets looks like:
"metadata": {
"field_sets_returned": [
"basic"
],
"field_sets_available": [
"basic",
"addresses",
"email_addresses",
"languages",
"phones",
"relationships"
],
"field_sets_default": [
"basic"
],
},To specify one or more field_sets to be returned the field_sets query string parameter is used to provide a comma separated list the field_sets being requested.
The UAPI specification defines a special field_set that doesn't directly correspond to a sub-resource. The basic field_set is used to represent a set of properties the resource will return when no field_sets are requested. These properties can include items from sub-resources as well as the top-level resource. If the query string for the request includes the field_sets or contexts parameter the basic field_set will NOT be included in the result unless it is part of the list of requested field_sets.
Sub-resources requested using the field\_sets query string parameter are represented as JSON objects at the top level of the individual resource representation. The name of the object is the name of the sub-resource. The representation of each sub-resource is exactly the same as if the sub-resource was accessed directly from the URL.
A request to https://api.byu.edu/byuapi/persons/123456789?field_sets=basic,addresses would look like:
{
"links":{...},
"metadata":{...},
"basic": {...},
"addresses": {...}
}Contexts are an optional part of the UAPI specification that allow APIs with a large number of field_sets to combine them into logical groups. This allows for simplification of the URL query string. Contexts should reflect the business domain related to the top-level resource. Field_sets can be included in multiple contexts.
If a top-level resource supports contexts it should add the contexts_available metadata to the field_set metadata. The value of this property is a JSON object consisting of a JSON array for each of the available contexts. The JSON array will contain the field_sets included in that context.
An example of the context metadata is as follows:
"contexts_available": {
"all": [
"basic",
"addresses",
"email_addresses",
"languages",
"phones",
"relationships"
],
"contact": [
"basic",
"addresses",
"email_addresses",
"phones"
],
"person_bio": [
"basic",
"languages"
]To specify a context or contexts to be returned the contexts query string parameter is used to list the contexts being requested. For example, using the above example context definitions, the query string parameter contexts=contact,person_bio would return the basic, addresses, email_addresses, phones, and languages field_sets.
Responses generated by using the contexts query string parameter are represented in exactly the same way as if the consumer had requested the included field_sets using the field_sets query string parameter. If the consumer specifies both the contexts and field_sets query string parameters the result should be a union of the field_sets requests. A field_set will only be included once in the result.
If the query string of a request contains an undefined field_set or context the entire request should be rejected with a HTTP status code of 400 Bad Request. A metadata property should be returned in the response body that contains the validation_response. validation_information should also be returned containing a message or messages indicating which query string parameter is the cause of the error.
A collection of resources can be filtered using query string parameters. Which of the properties of a resource can be used as filters in the query string is left to the API to define and should follow the business use cases of the top-level resource and follow any authorization rules for the property (see 11.4 Filter Authorization). For example our persons top level resource uses byu_id as its primary key. Unfortunately byu_id is only one of three keys in common use to access the persons resource. If a consumer wants to find a person with a specific net_id then a query string parameter of net_id should be supported by the API. Likewise it makes sense to allow for filtering on other properties such as email_address or phone_number. Information in the Swagger definition for the API should include which properties can be used for filtering.
Filter parameters given in the query string should correspond to properties provided by the resource and should be defined in the Swagger definition of the resource. The field_sets and contexts query string parameters can be combined with filter parameters to customize the resulting representation.
Multiple filters can be combined to create more complex filtering rules. APIs can also support multiple values per filter parameter (comma separated) as well. When multiple values are specified in a filter parameter the values are "OR"ed together. Multiple filter query string parameters are "AND"ed together.
Filters apply to the lowest level resource specified on the URL. If the URL only specifies a top level resource a collection of top level resources that match the filter will be returned. If the URL includes a sub-resource the filter will be applied to that sub-resource and the collection returned will be instances of the sub-resource. For example, the URL https://api.byu.edu/byuapi/persons?net_id=johndoe will return a collection of persons that have a net_id of johndoe. The URL https://api.byu.edu/byuapi/persons/123456789/addresses?address_type=MAL will return a collection of all mailing addresses associated to the person with the byu_id 123456789 that have an address_type of MAL.
There are times when it makes sense to query a top level resource by a value in one of the sub resources. For example, if I want a list of persons whose home address is in a certain zip code. Resources can support this type of query by implementing dot (.) notation. Dot notation allows for a filter parameter to specify the relationship between a top level and a sub-resource property. In order to implement the above example the query string would look something like https://api.byu.edu/byuapi/persons?addresses.address_type=HOM&addresses.zip_code=84604 would return a collection of persons with a home address in the 84604 zip code.
Individual resources can choose to support a wildcard in their query string parameters where they make sense. The asterisk (*) should be used as the wildcard character for consistency across resources.
Filters can optionally support operators. The format of a filter including an comparison operator is filter_name[operator]=value(s). The following comparison operators are supported.
| Operator | Notes | Example |
|---|---|---|
| none(default) | Exact match is required. If the filter supports multiple comma separated values the values are "OR"ed together. | https://api.byu.edu/byuapi/persons?net_id=johndoe |
starts_with |
The property starts with the provided parameter | https://api.byu.edu/byuapi/persons?net_id[starts_with]=john |
ends_with |
The property values end with the provided parameter | https://api.byu.edu/byuapi/persons?net_id[ends_with]=doe |
contains |
The property values contain the provided parameter | https://api.byu.edu/byuapi/persons?net_id[contains]=john |
gt |
The property values are greater than the provided parameter | https://api.byu.edu/byuapi/persons?net_id[gt]=johndoe |
gt_or_eq |
The property values are greater than or equal to the provided parameter | https://api.byu.edu/byuapi/persons?net_id[gt_or_eq]=johndoe |
lt |
The property values are less than the provided parameter | https://api.byu.edu/byuapi/persons?net_id[lt]=johndoe |
lt_or_eq |
The property values are less than or equal to the provided parameter | https://api.byu.edu/byuapi/persons?net_id[lt_or_eq]=johndoe |
not_eq |
The property values are not equal to the provided parameter | https://api.byu.edu/byuapi/persons?net_id[not_eq]=johndoe |
is_null |
Returns true/false depending upon if the property value is null |
https://api.byu.edu/byuapi/persons?net_id[is_null]=true |
is_empty |
Returns true/false depending upon if the property value is empty |
https://api.byu.edu/byuapi/persons?net_id[is_empty]=true |
not_in |
The property values are not in the list contained in the provided parameter. Only applicable for filters that allow for multiple values | https://api.byu.edu/byuapi/persons?net_ids[not_in]=johndoe,janedoe |
The provider should include in the documentation for the service which operators are allowed for their specific filters.
Filters allow for limiting the contents of a request. An API can optionally support the ability for a consumer to search across a predefined set of properties for resources containing specific text.
Searching can be done across multiple properties at the same time. APIs group searchable properties into search contexts. Each property in a search context should be logically related. Searches can only be performed against a single search context per request. Searches can be combined with filters to allow for complex operations. The valid combinations are API dependant and should be outlined in the API documentation.
If a resource supports searching it should add the search_contexts_available property to its metadata . The value of this property is a JSON object consisting of a JSON array for each of the available search contexts. The JSON array will contain the properties included in that search context in the order they will be searched.
An example of the search context metadata is as follows:
"search_contexts_available": {
"identifiers": [
"net_id",
"sort_name",
"byu_id"
],
"names": [
"preferred_last_name",
"last_name",
"preferred_first_name",
"first_name"
],
"locations": [
"home_country",
"home_state"
]The query parameters used to specify search criteria are as follows:
| Parameter | Description |
|---|---|
| search_context | The search context to use. |
| search_text | The text to search for in the specified context. |
Search results are returned as a collection. The validation_information metadata property on each instance returned can be used to give information about why the instance was selected. The order of the instances in the collection is determined by the API. Results of the request will be sorted before applying any subset parameters specified in the request (see 3.3.5 Large Collections).
Resources often have associated sets of terms, like accepted state and country names and their abbreviations, that define possible values for properties. These terms, or controlled vocabularies, are necessary for a client to properly use the API. The controlled vocabularies associated with a UAPI compliant resource should be made available through an API published in the the meta URL namespace.
Each controlled vocabulary should have a corresponding API with the following characteristics:
- The API should be located under
https://api.byu.edu/byuapi/meta/<top-level-resource>/<vocabulary-name>. - Meta APIs should provide HTTP GET support only. Updating values in the controlled vocabulary is left to the domain APIs supporting the data set.
- Meta API responses do not include
metadataorlinkssections like regular UAPI top level resource responses. - Meta APIs provide a single GET verb on the URL
https://api.byu.edu/byuapi/meta/<top-level-resource>/vocabulary-name>that returns the controlled vocabulary as a JSON array. - Meta APIs do not support paging.
Controlled vocabularies that are referenced using the domain property of the properties metadata (3.2.3 Properties) should be structured as follows:
{
"value":"<value of this term in the controlled vocabulary>",
"description":"<short description of this term>",
"long_description": "<long description of this term>"
}- All three properties are required and should be not be empty.
- Values for
descriptionandlong_descriptioncan be derived from other properties of the data set to provide a standard way to represent each entry in the data set. descriptionshould be limited to 30 characters in length. It is intended for uses like populating a drop-down list.long_descriptionshould be limited to 256 characters in length.
An HTTP GET with the application/json mime type on the state_codes data set located at the URL https://api.byu.edu/byuapi/meta/students/state_codes would return the following:
{
"values": [
{
"value": "ID" ,
"description": "Idaho",
"long_description":"Idaho"
},
{
"value": "NV" ,
"description": "Nevada",
"long_description":"Nevada"
},
{
"value": "UT" ,
"description": "Utah",
"long_description":"Utah"
},
{
"value": "VT" ,
"description": "Vermont",
"long_description":"Vermont"
},
...
]
}Meta Data Sets are considered public. No authorization rules other than any API Manager subscription requirement should be enforced on these APIs.
Errors encountered while accessing any Meta URL data set should simply return the appropriate HTTP status code. UAPI error processing as outlined in 12.0 Errors is not required.
Files includes images, PDFs, text files, JSON files, etc. Files appear as sub-resources in the URL space of the UAPI but are treated differently.
Supporting downloads of these files via the UAPI is done through standard REST practices. All files should be directly accessible in a URL space that is part of the UAPI URL space and protected by appropriate measures including requiring an HTTP Authorization header. Requests to the URL for a file with no HTTP Accept header or the mime-type of the file should return the file in standard HTTP fashion.
Many files have data associated with them such as creation-date, owner, etc. Requests to the URL for a file with the HTTP Accept header containing the mime-type application/vnd.byu.uapi+json will return data associated with the file in standard UAPI format. The mime-type application/vnd.byu.uapi+json is used to avoid the instance where the file itself is a JSON file.
Uploading of files is left to the discretion of the API designer but should follow standard industry practices.
Updating file metadata should be done using standard UAPI POST, PUT, and DELETE methods (see 10.0 HTTP POST, PUT, DELETE with the mime-type of the request being application/vnd.byu.uapi+json.
The UAPI spec defines the HTTP PUT and POST verbs (respectively) for modifying and creating new top level and sub-resources. The resource body used in the request is field_set specific. Generally it is a JSON structure containing all properties as name/value pairs that can be modified for that field_set.
The HTTP PUT verb is used to modify a resource. PUTs against the top level resource will update the basic field_set. All other PUTs will be to the URLs of sub-resources associated with the field_set.
For example, to update the basic field_set of the persons resource a PUT is sent to the URL https://api.byu.edu/byuapi/persons/123456789 with the request body as follows:
{
"first_name": "Abernathy",
"high_school_code": "050714",
"home_country_code": "USA",
"home_state_code": "UT",
"home_town": "Provo",
"middle_name": "Cosmo",
"preferred_first_name": "Cosmo",
"preferred_surname": "Cougar",
"restricted": false,
"sex": "M",
"suffix": "II",
"surname": "Cougar-Rodriguez"
} To update the work mailing address of a person resource a PUT is sent to the URL https://api.byu.edu/byuapi/persons/123456789/addresses/WRK with the request body as follows:
{
"address_line_1": "1234 Milky Way",
"address_line_2": "Highland, UT 84003",
"address_line_3": " ",
"address_line_4": " ",
"building": " ",
"city": "Highland",
"country_code": "USA",
"postal_code": "84003",
"room": " ",
"state_code": "UT",
"unlisted": false,
"verified_flag": true
} When the update is completed successfully an HTTP Status Code of 200 should be returned. The body of the response should contain either the field_sets that were updated or the sub-resource that was updated.
There are occasions where PUT can be used to create a resource (usually a sub-resource). These occur when the identifier for the sub-resource can be determined before the sub-resource is created. For example, when there exists a defined set of possible identifier values such as the address_type of an address resource. The API may assume a PUT to the sub-resource will create an address of the specified type if one of that type doesn't already exist. So a PUT to the URL https://api.byu.edu/byuapi/persons/123456789/addresses/WRK would use the values in the body to update the address resource if one exists, otherwise it would create a new resource with that address_type.
Caution should be taken to ensure the logic required to determine the identifier is as minimal as possible to prevent the consumer from having to understand the logic behind identifier creation.
When a new resource is created an HTTP Status Code of 201 should be returned along with the Location HTTP header containing the URL for the new resource. The body of the response should contain either the basic field_set or the sub-resource just created.
The HTTP POST verb is used to insert a new resource or sub-resource. Due to the complexities of creating a new resource the UAPI spec does not specify a format or restrictions on the request body. When a new resource is created an HTTP Status Code of 201 should be returned along with the Location HTTP header containing the URL for the new resource. The body of the response should contain either the basic field_set or the sub-resource just created.
The UAPI spec also defines the HTTP DELETE verb for deleting top level and sub-resources. If the DELETE is successful an HTTP Status Code of 204 No Content should be returned. No response body should be returned.
Upon successful completion of a PUT or POST the return representation should be the resource that was updated in the standard UAPI format.
If errors in the request prevent the POST or PUT from happening the appropriate HTTP Status Code should be returned along with a minimal UAPI standard result representation. Specifically, the metadata properties validation_response and validation_information should be used to convey additional information to the client about the errors that occurred. Notice validation_information is an array in order for information about all errors that occurred when processing the request can be returned to the client.
For example, the following response could be returned when there are multiple validation errors.
"metadata": {
"restricted": false,
"validation_response": {
"code": 400,
"message": "Bad Request"
},
"validation_information": [
"Invalid home_country_code",
"Invalid home_state_code",
"first_name required"
]
},For more information about handling errors see 12.0 Errors
Authorization for access to UAPI resources falls back to the authorization schemes of individual domains. The UAPI specification only defines what level of authorization is allowed and how denied authorization is communicated to the consumer.
Authorization in the UAPI is done at the field_set/sub-resource level. Authorization at the property level is not allowed. Properties should be grouped into field_sets that share common authorization business requirements along with matching the model of the resource as closely as possible.
Authorizing by field_set introduces the dependency that the data classification (see data classification definitions) for the entire field_set is the data classification for the most restricted property it contains. The same applies for complex objects that are included as part of a field_set.
In order for a consumer to have access to any part of a top level resource or sub-resources of the top level resource the consumer must at least have access to the basic field_set. Access to other field_sets/sub-resources is optional.
Authorization of access to properties is controlled at the field_set level. Access to a field_set implies that at least read-only access is allowed for all properties contained in the field_set. A field_set may contain a mix of read-only and modifiable properties.
When selecting properties to offer as filters on resources care needs to be taken to ensure that carefully constructed filtering of resources doesn't allow for inferring data the consumer is not authorized to have. Requests that include filter properties on the query string should be checked for proper authorization to the properties being requested. In general the consumer must have access to at least one field_set that includes the requested property in order to be authorized to filter on that property.
If a filter request fails the authorization check the request should be rejected and a 403 Unauthorized should be returned to the consumer.
Authorization failures should be communicated via standard HTTP Status Codes, typically using the 403 Unauthorized status code.
If the consumer does not have authorization to access any part of a top level resource the appropriate status code should be returned for the entire request. The body of the response should contain at least the metadata section with the appropriate validation_response and validation_information properties populated.
If the consumer requests direct access (via the URL) to a sub-resource that is not authorized the response code and response body should be the same as for a forbidden top-level resource request.
If the consumer requests access to multiple sub-resources via field_sets or context query parameters the response should be as follows:
- If the consumer does not have access to the top level resource the response should be as outlined in 11.5.1.
- If the consumer does have access to the top level resource the response code for the request should reflect the status of access to the top level resource (e.g.
200if the resource is accessible,404if not found, etc.). Each field_set property in the response body should reflect the status of access to that field_set by setting thevalidation_responseproperty of themetadatasection of the field_set. Requested field_sets should always be included in the response body of the request even if they are unauthorized. Unauthorized field_sets will only have theirmetadataproperties set in the response body.
Persons related to the university can request that their records be restricted. A person that has their restricted flag set essentially does not exist for any system that is not authorized to see restricted persons. All resources that deal with any aspect of an individual must implement the restricted resources specification requirements. Resources that do not deal with individuals may include the metadata element with the value always set to false.
The metadata property for all top level and sub-resources must have the restricted element. That element should always be set to the value of the restricted flag for the person (true/false). The property should appear for all resources even if the consumer does not have access to restricted resources.
Because collections of top level resources represent multiple resources they do not include the restricted element. Each resource within the collection will have the restricted element for that resource. Collections of sub-resources do have the restricted element because they represent an aspect of the top-level resource which may represent a restricted individual.
Access to restricted records by consumers with restricted record authorization should be no different than accessing any other resource provided by the API. The restricted element of the metadata property should be set to true to indicate to the consumer that the resource they are accessing is restricted. Consumers are then obligated to follow established guidelines regarding handling of restricted resources.
An attempt to access a restricted top level or sub-resource by an unauthorized consumer should result in exactly the same result as the API would give if the resource did not exist. Typically the HTTP status code of 404 - Not Found would be returned.
Each resource and collection of resources in the JSON response body has a metadata property. The sub-properties validation_response and validation_information are used to convey to the consumer information about the state of the resource or resource collection.
Standard HTTP status codes should be used for the overall status of the request and for each sub-resource request included in the request.
The response body should be formatted in standard UAPI format with only the metadata section being required. The metadata section should include the validation_response with the HTTP status code and description. The optional validation_information metadata property can also be included to provide additional information to the consumer about the reasons for the request failure.
The validation_response metadata property should contain the HTTP status code and description for the operation requested on the resource in the following format:
"validation_response": {
"code": 200,
"message": "Success"
}The optional validation_information metadata property can be used to communicate multiple status messages about the operation requested on the resource. It is a JSON array in the following format:
"validation_information": [
"Invalid home_country_code",
"Invalid home_state_code",
"first_name required"
]There are instances where an entry in a collection has an error while other entries in the collection do not. The optional validation_identifiers metadata property on the specific entry in the collection can be used to communicate the identifers for that entry in the collection that has the error. This allows the API designer to include in the error an appropriate level of detail as to which entries in a collection had errors. Care should be taken to be sure no unauthorized information is leaked by including the identifiers in the error. The validation_identifiers property is represented as an object with the following format:
"validation_identifiers": {
"byu_id": "123456789",
"address_type": "MAL"
}The properties included in the validation_identifers should be consistent regardless of the type of error returned.
Requests for top level resources take three forms - requests for collections of resources (no identifier on the resource URL) and requests for specific resources (identifier included in the URL) and either of the two with field_sets or contexts query string parameters.
Errors in processing a request for a single top level resource with no additional field_sets requested should be returned as the HTTP status code for the request as well as the basic field_set representation containing at least the metadata property with the validation_response and optionally the validation_information property.
Errors in processing a request for a collection of top level resources should proceed as follows:
- If an error occurs with the overall request the HTTP status code for the request should indicate the type of error that occurred. The body of the response should contain a UAPI standard format response containing at least the
metadataproperty with thevalidation_responseproperty and optionally thevalidation_informationproperty. - If an error occurs in processing the request for one or more of the resources in the collection the
validation_responseandvalidation_informationmetadata properties for that resource should be set with the appropriate error information. Optionally thevalidation_identifiersproperty can be set with the identifiers for the entry with the error. The HTTP status code for the entire request may be a200 Successeven if only part of the response is error free.
Errors during access to individual sub-resources with or without identifiers should be handled the same way as top level resources outlined in 12.3 Top Level Resource Errors.
A single request to a top level resource requesting multiple sub-resources via field_sets or contexts presents the possibility that some sub-resource access may fail while others will succeed. To reflect this situation the following rules apply:
- The HTTP status code for the entire request is
200 Success. - The field_set properties for parts of the response that experienced errors will contain at least the
metadataproperty with the appropriate values for thevalidation_response,validation_information, andrestrictedproperties. - The field_set properties for parts of the response that succeeded will contain the UAPI representation of the field_set with the
validation_responseset to the appropriate HTTP status code, normally200 Success.
Because of the need to protect restricted resources (see 11.6 Restricted Resources), when a 404 Not Found is to be returned special rules apply:
- If the request is for a single top-level resource or sub-resource addressed directly via the URL the
404 Not FoundHTTP status code should be returned with no body attached to the result. - If the request is for a top-level resource (single or collection) that includes multiple sub-resources via field_sets or contexts and one or more of the sub-resources is not found the rules for Partial Error Response 12.5 Partial Error Response apply.
When a request contains an undefined query parameter or a query parameter that contains an invalid value the HTTP status code 400 Bad Request should be returned and the body of the message should contain a valid validation_response. In order to aid the consumer with correcting the problem the API should include the validation_information metadata property with messages that specify which query parameter(s) was problematic and why.
| Version | Date | Changes |
|---|---|---|
| 1.0 | Original published standard | |
| 1.1 | Complete rewrite of the standard document to include new items such as field_sets, contexts, etc. All information about domain APIs has been moved to a separate document. | |
| 1.2 | May 31, 2018 | Added date/time specification, clarified top level resource links and metadata, fixed dot notation example. |
| 1.3 | July 19, 2018 | Added requirements around restricted persons including clarifying how 404 errors are to be handled. Added 403 error for invalid field_set and context parameters. Added sections for sorting, subsets of large collections, and search. Other minor enhancements and clarifications. |
| 1.4 | ? | Added support for complex objects and specify which data types are acceptable. |
| 1.5 | ? | Added support for conditional operators on filters. |