Standards and Guidelines that apply to all TIER RESTful APIs
Common invalid requests
Any resource/method that has these situations should use these common error codes
TIER result code | HTTP response code | Success? | Request description |
---|---|---|---|
ERROR_METHOD_NOT_AVAILABLE | 405 | false | Method that is not available for a resource |
ERROR_PAGING_INVALID | 400 | false | If paging is not sent in correctly |
ERROR_MULTIPLE_PARAMS | 400 | false | If multiple request parameters were sent when one was expected |
ERROR_INVALID_REQUEST_BODY | 400 | false | If a body was sent in the request and not expected |
ERROR_ID_EXPECTED | 400 | false | If an ID of a resource was expected and not sent in, e.g. if deleting a group but the group ID was not specified. Note, this request could also generate ERROR_METHOD_NOT_AVAILABLE. It is up to the implementer, this response code might be more helpful |
ERROR_INVALID_PATH | 404 | false | If too many URL strings are passed in. e.g. if this GETs a group: /Groups/id:abc, then this would generate this response error: /Groups/id:abc/something. Similarly, if a path element has an invalid path (e.g. if the format of an ID in the path is not correct), this the same condition. If a misspelled or mistaken path element is specified (e.g. /Gruops ) then this is the same condition. Note: if the path is valid but the resource is not found (e.g. cant find the group), then a more specific TIER result code should be used. |
ERROR_INVALID_PARAM | 400 | false | If a parameter required a specific format or list of values and is invalid. Note, if a more specific ERROR_ result code is desired that could be used instead |
ERROR_NOT_AUTHORIZED | 403 | false | If the resource exists but it not allowed to be read / updated / inserted / deleted by the authenticated user |
ERROR_EXCEPTION | 500 | false | If an unexpected exception was thrown |
Misc
Common parameters
Parameter name | Values | Description |
---|---|---|
indent | true|false | if the output should be formatted to be easy to read |
Standards and guidelines that apply to all TIER APIs
Category | Description of guideline/standard | Constraints/exceptions | Supporting work/issues/resources |
---|---|---|---|
Relation to SCIM | |||
API operations | For all API operations that can be found in SCIM, follow the SCIM protocol as defined in RFC7644 |
| |
Schema | Relationship of TIER schema with SCIM-defined schema, RFC7643 |
| On making schema compliant and extensible, see: |
Resource types | Follow SCIM Protocol Section 6 when defining additional resource types | ||
Requests | |||
HTTP verbs | Customary definition of HTTP verbs (e.g., GET, PUT, POST, DELETE) will be followed. | In some cases it will be necessary to specify different nuances in different contexts. | See: https://www.ietf.org/rfc/rfc2616.txt |
URI syntax | Follow REST conventions |
| |
Resource (URI) syntax | Resource reference syntax |
| |
Object references | Objects can be referred to in various ways without having to do superfluous lookups. Objects should have a primary identifier. This identifier should not change. Therefore it should be opaque to allow for renames. Objects can be referred to by other unique identifiers as well. Unique identifiers that are not the primary identifier can change. Prefixes specify how the objects are referred to. |
Examples: URL of user by opaque id: https://people.institution.edu/entities/id:1234567 URL of user by netid: https://people.institution.edu/entities/netId:jmith URL of groups for a user by eppn: https://groups.institution.edu/entities URL to determine if Person p is in a Group g https://groups.institution.edu/groups/name:edu:institution:community:employees |
2. Regarding, first example: URL of user by opaqueid: https://people.institution.edu/entities/id:1234567 Note to discuss whether Entity can cover both Users and Groups |
Searches and queries | Filtering syntax for searches and queries follows SCIMsection 3.4.2.2 | ||
Pagination | Follow SCIM section 3.4.2.4 on pagination | ||
Parameter passing and syntax | Parameters can be passed to resource requests in the body of the POST or as URL parameters (e.g. ?paramName=paramValue) |
| |
Responses | |||
Response format | JSON |
| |
Response content | Representations (such as users, groups) |
| Example of representation of user in response: https://spaces.at.internet2.edu/display/DSAWG /TIER+API+SCIM+group+member |
Metadata | Standardized elements of response metadata | ||
Response codes | HTTP response codes will not be overridden but enriched | HTTP response codes are not entirely unambiguous with respect TIER response codes should be capital letters (could have numbers) where words are separated by underscores. Successful response codes should start with SUCCESS (or be equal to SUCCESS. Unsuccessful response codes should start with ERROR
|
|
TIER HTTP headers |
| Headers should be named: X-TIER-someName where the last string is lower-case camelcase Related to numbered items in preceding column:
Note: If the request requires authentication and none is sent, a 401 HTTP status code will be | |
Securing APIs | |||
HTTPS | |||
Techniques for securing API operations are currently external to the API. | Future versions of this guideline may be more prescriptive. (Reference auth types suggested are HTTP Basic and SSL certificates. If the request requires authentication and none is sent, a 401 HTTP status code will be returned. In such cases, there might be no TIER headers since this status code could have been sent by the web server. | Assumes API is passed the value of the authenticated identity. | |
API specification | |||
Swagger specification and compliant tools. |
|
Meta
Each response should have a "meta" attribute with the following structure. Note, some error conditions will prevent this attribute from being sent back. See the SCIM definition
Field | Type | Required | Description |
---|---|---|---|
resourceType | String | true | The name of the resource type of the resource. This attribute has a mutability of "readOnly" and "caseExact" as "true". e.g. for groups it is "Group" |
created | DateTime | false | The "DateTime" that the resource was added to the service provider |
lastModified | DateTime | false | The most recent DateTime that the details of this resource |
location | String URI | true | The URI of the resource being returned. This value MUST be the same as the "Content-Location" HTTP response header (see Section 3.1.4.2 of [RFC7231]). |
version | String | false | The version of the resource being returned. This value must be the same as the entity-tag (ETag) HTTP response header (see Sections 2.1 and 2.3 of [RFC7232]). This attribute has "caseExact" as "true". Service provider support for this attribute is optional and subject to the service provider's support for versioning (see Section 3.14 of [RFC7644]). If a service provider provides "version" (entity-tag) for a representation and the generation of that entity-tag does not satisfy all of the characteristics of a strong validator (see Section 2.1 of [RFC7232]), then the origin server MUST mark the "version" (entity-tag) as weak by prefixing its opaque value with "W/" (case sensitive). |
tierCanonicalLocation | String URI | false | If this response refers to another object, that URI is specified here. For example i you are requesting /Groups/id/Members/id, the response is a User or Group or System, and the canonical location would be the Group or User or System URI |
tierSuccess | boolean | true | Same value as X-TIER-success |
tierServiceRootUrl | String URI | true | The root URI for this service: https://groups.institution.edu/groupsApp/tierApiAuthz |
tierServerVersion | String | true | Same version as URL though could have a build number on end after dot: e.g. v1.123 |
tierResultCode | String | true | Same value as X-TIER-resultCode, e.g. SUCCESS |
tierRequestId | String | true | Same value as X-TIER-requestId |
tierResponseDurationMillis | int | false | Same value as X-TIER-responseDurationMillis |
tierErrorMessage | String | false | If this is an error this can hold the free form error message |
tierHttpStatusCode | int | true | http status code of the response |
tierWarning | String | false | free form warnings for example if superfluous params were sent |
tierDebugMessage | String | false | could be sent to give debug info for this request |
Archive: Numbered list of standards and guidelines for RESTful APIs in TIER
Archived Comments