Internet2 is investigating a security incident involving a compromise to a confluence server that affected https://spaces.at.internet2.edu on April 10, 2019, which was successfully mitigated on April 12, 2019. If you did not receive an email from us, it’s unlikely that any of the content you submitted to the Internet2 Spaces Wiki needs to be re-entered. We apologize for any inconvenience this may have caused. Should you have any questions or require further assistance, please email collaboration-support@internet2.edu.
Child pages
  • TIER Standards and Guidelines
Skip to end of metadata
Go to start of metadata

Standards and guidelines that apply to all TIER APIs


CategoryDescription of guideline/standardConstraints/exceptionsSupporting work/issues/resources
Relation to SCIM

RFC 7642, SCIM Definitions, Overview,

Concepts, and Requirements

API operationsFor all SCIM 2 API operations that are useful in TIER, follow the SCIM protocol as defined in RFC 7644Some APIs, including the IdMatch API (for identity de-duplication and reconciliation), do not fit well in the SCIM design space.
  1. See SCIM at: https://tools.ietf.org/html/rfc7643 andhttps://tools.ietf.org/html/rfc7644
  2. See initial TIER group operations at:
    https://spaces.at.internet2.edu/display/DSAWG
    /Initial+Set+of+TIER+Group+Management+APIs
  3. See also: https://bugs.internet2.edu/jira/browse/TIERAPI-1
Resource Types and SchemaRelationship of RFC 7643 SCIM-defined Schema and Resource Types to TIER Schema and Resource Types.
  1. Some TIER resources (e.g., Non-person Security Principals, Group Memberships (reified User-Group associations), Systems of Record). In those cases, TIER will follow the SCIM procedures for defining new Resource Types aid out in RFC 7643, Section 6.
  2. Each schema element used in TIER-defined extensions and Resource Types will be defined with a TIER schema.
  3. SCIM Resource Types that are suitable to TIER purposes (e.g., User, Group, Schema) will be used in TIER. When additional elements are needed, TIER will define schema extensions by the mechanisms set out in RFC 7643.

On making schema compliant and extensible, see:

https://spaces.at.internet2.edu/display/DSAWG/Ignoring+Unrecognized+
Schema+Fragments+in+a+Received+Resource+Representation

Requests 
HTTP verbsCustomary 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

As one example, the major version of the client is included in the URL path, e.g.: https://groups.institution.edu/tierServer/v1/Groups

 
Resource (URI) syntaxResource reference syntax
  1. Resource Type names should be Pascal case starting with a capital letter.
  2. REST practice conventions will be followed with respect to plurals: Resource Type names are singular (User). However, In URL paths, Resource names are given in plural form (/Users/...
  3. If you have a resource that has a sub-resource, then you need to specify that sub-resource in the path.
    1. Do this: /Users/some:id/Roles/role:id
    2. Not: /Users/some:id/role:id
    3. For example,  /myTierServer/Users/id:abc/Groups/groupName:edu:institution:whatever
  4. The major version of the client is in the URL:https://entities.institution.edu/Groups/v1

 
Resource instance references

Resource instances can be referred to in various ways without having to do superfluous look-ups.

Resource instances should have a primary identifier. This identifier should not change. Therefore it should be opaque to allow for renames.

Resource instances can be referred to by other unique identifiers as well. Unique identifiers that are not the primary identifier can change.

Prefixes on Resource instance identifier values specify the type of identifier that follows

  1. Type-indicating prefixes on resource instance identifiers must be alphanumeric, therefore they must not contain colons or whitespace.
  2. Type-indicating prefixes must be separated from the identifier value proper by a colon.
  3. It is recommended that institutions use prefixes with part of the prefix related to the institution
    (e.g. the pennkey at penn could have a prefix "pennkey")
  4. The TIER-defined prefixes are:
    1. id - this is the unchanging primary identifier of the object
    2. name - if applicable, this is the system name of the object (e.g. the name which doesn't 
      change much and which might not be opaque, e.g. the group name)
    3. index - if applicable, this is the numeric index of the object, e.g. the posix ID of the group
    4. uniqueAttribute - this will lookup one object by any of the id or any unique attribute. if it finds 
      multiple objects, it will return an error
    5. loginId - if applicable, this will lookup an object by a netId
    6. eppn - if applicable, this will lookup an object based on the scoped netId or whatever
      is used for eppn
    7. other Tier-defined prefixes will begin with the string "tier"

Examples:

URL of user by opaque id: https://entities.institution.edu/users/id:1234567

URL of user by netid: https://entities.institution.edu/people/netId:jmith

URL of groups for a user by eppn: https://entities.institution.edu/people/eppn:jsmith@institution.edu/groups

URL to determine if Person p is in a Group g https://entities.institution.edu/groups/name:edu:institution:community:employees
/members/uniqueAttribute:1234543

 

  1. See recent discussion at bottom of: https://spaces.at.internet2.edu/display/DSAWG/TIER+API+SCIM+common+elements. For example, a URL of a user identified by an opaqueid might be https://people.institution.edu/users/id:1234567

 

Searches and queriesFiltering syntax for searches and queries follows SCIM RFC 7644, section 3.4.2.2TIER defined prefixes causing problems - JIRA issue 
PaginationFollow SCIM RFC 7644, section 3.4.2.4 on paginationDynamic objects impact reliability. 
Parameter passing and name/value syntax

Parameters can be passed to resource requests in the body of the POST or as URL parameters (e.g. ?paramName=paramValue)

  1. Parameter names defined in TIER APIs not found in SCIM must begin with "tier" followed by the desired parameter name.
  2. Parameter names and values are case sensitive.
  3. Parameter names should be camel case (starting with lower case).
  4. ENUMs should be camel case.
  5. Boolean parameters should have the value "true" or "false".
  6. If a resource allows a site to add a parameter name, the site name should begin with a camel case two or three-level domain name (e.g. "wiscEduLocalParameter", "oxbridgeAcUkLocalParameter")
 
Responses   
Response formatJSON
  1. In some cases we will define constraints on JSON string values, 
    e.g. for calendar dates, the JSON type will be string, but TIER will specify that the string values must conform to ISO 8601 'calendar date' format.
 
Response contentRepresentations (such as users, groups)
  1. Different clients (identified by authenticating credential) might see different responses
    1. This might be due to the privileges that the clients have on the data
    2. This might be due to a server configuration that returns more optional data elements
Example of representation of user in response:
https://spaces.at.internet2.edu/display/DSAWG
/TIER+API+SCIM+group+member
MetadataStandardized elements of response metadataSCIM Resources with TIER schema extensions will have "meta" elements in both the core SCIM representation and also in the TIER extension representation. To preserve consistency for developers, TIER Resources will have the same.JIRA issue
Response codesHTTP response codes will not be overridden but enriched

HTTP response codes are not entirely unambiguous with respect
to all resource operations so supplemental response information will be provided.

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

 

  1. TIER discussion thread:
    [tier-api] HTTP response code
  2. Tracked in: https://bugs.internet2.edu/jira/browse/TIERAPI-2
  3. Examples of TIER response codes here:
    https://spaces.at.internet2.edu/display/DSAWG
    /TIER+API+SCIM+group+member
  4. See recent discussion at bottom of: 
    https://spaces.at.internet2.edu/display/DSAWG
    /TIER+API+SCIM+common+elements
TIER HTTP headers
  1. X-TIER-success: required, boolean, true or false
  2. X-TIER-resultCode: required, string, corresponds to the result code in the body.
  3. (optional) X-TIER-requestId: unique URL for the request that can be used for troubleshooting, auditing, or logging
  4. (optional) X-TIER-responseDurationMillis: integer, number of milliseconds that the server took to process the request.

 

Headers should be named: X-TIER-SomeName where the last string is Pascal case

Related to numbered items in preceding column:

1) "true" means the TIER API server successfully handled the request. Even if the response is false there might be a body to parse

Generally this is implemented on the server with exception handling. If there is an exception and any database transactions are rolled back then the response is false.

Note that there will be cases where looking up a resource the HTTP status code might be 404 but X-TIER-success is still true.

If a batched request is partially successful then this response code should be true if it can be returned. The body should give details about the failure.

2) There should only be a handful of valid response codes for a given request resource and HTTP method

 
Securing APIs   
 HTTPS  
 Techniques for securing API operations are currently external to the API.

Future versions of this guideline are likely to be more prescriptive.

Possible authentication methods include HTTP Basic over TLS, SSL client authentication, OAuth 2, and OpenID Connect.

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 headers since this response could be sent by the web server, bypassing the TIER component entirely.

Need to collect and document methods for securing APIs that we (the TEIR development community) uses

Assumes the value of the authenticated identity is passed in the API call

API specification   
 Swagger specification and compliant tools.The normative specification for TIER APIs and Schema will be expressed as Swagger 2
  1. See swagger spec:
    http://swagger.io/specification/
  2. Swagger tools:
    http://swagger.io/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

FieldTypeRequiredDescription
resourceTypeStringtrueThe 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"
createdDateTimefalseThe "DateTime" that the resource was added to the service provider
lastModifiedDateTimefalse

The most recent DateTime that the details of this resource were updated at the service provider. If this
resource has never been modified since its initial creation, the value MUST be the same as the value of "created".

locationString URItrueThe 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]).
versionStringfalseThe 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 URIfalseIf this response refers to another object, that URI is specified here. For example if 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
tierSuccessbooleantrueSame value as X-TIER-success
tierServiceRootUrlString URItrueThe root URI for TIER API calls: https://entities.institution.edu/
tierServerVersionStringtrueSame version as URL though could have a build number on end after dot: e.g. v1.123
tierResultCodeStringtrueSame value as X-TIER-resultCode, e.g. SUCCESS
tierRequestIdStringtrueSame value as X-TIER-requestId
tierResponseDurationMillisintfalseSame value as X-TIER-responseDurationMillis
tierErrorMessageStringfalseIf this is an error this can hold the free form error message
tierHttpStatusCodeinttruehttp status code of the response
tierWarningStringfalsefree form warnings for example if superfluous params were sent
tierDebugMessageStringfalsecould be sent to give debug info for this request

Common invalid requests

Any resource/method that has these situations should use these common error codes

TIER result codeHTTP response codeSuccess?Request description
ERROR_METHOD_NOT_AVAILABLE405falseMethod that is not available for a resource
ERROR_PAGING_INVALID400falseIf paging is not sent in correctly
ERROR_MULTIPLE_PARAMS400falseIf multiple request parameters were sent when one was expected
ERROR_INVALID_REQUEST_BODY400falseIf a body was sent in the request and not expected
ERROR_ID_EXPECTED400falseIf an ID of a resource was expected and not sent in, e.g. if deleting a group but the group ID was not specified.
ERROR_INVALID_PATH404falseIf 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_PARAM400falseIf 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_AUTHORIZED403falseIf the resource exists but it not allowed to be read / updated / inserted / deleted by the authenticated user
ERROR_EXCEPTION500falseIf an unexpected exception was thrown

Misc

Common parameters

Parameter nameValuesDescription
indenttrue|falseif the output should be formatted to be easy to read ("pretty print")

 

Event Message Standards and Guidelines

 

CategoryDescription of guideline/standardConstraints/exceptionsSupporting work/issues/resources
Message Payload   
 Message payloads must contain a resolvable reference to a representation of the current state of the resource in question or the resource representation itself  
 The representation of a given resource must be the same whether obtained via Messaging or via API  
 Standard metadata must accompany each message payload  
    
Configuration   
 Explicitly declare supported guarantees for use as needed: One-time delivery; At least one-time delivery; Order preserved, etc.  
    
    
...   

Archive: Numbered list of standards and guidelines for RESTful APIs in TIER 

Archived Comments