• 2) For all API operations that can be found in SCIM, TIER will follow the SCIM protocol

  • 3) Each schema element used in TIER will be defined within a TIER schema. Any element defined in SCIM that would be useful as is in TIER will have a TIER equivalent element with an identical name and definition.  Where it makes sense we want backward compatibility with SCIM;  We want a TIER User resource and a future TIER Person resource.

  • 4) As with SCIM and Grouper, the choice of security methods is not mandated in the API.  
    • Some suggested authentication methods are basic auth over TLS and mutual authentication via SSL certificates. 
    • Future versions of this guideline may be more prescriptive.
    • 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.

  • 5) Follow SCIM Section 6 when defining additional resource types

  • 6) Semantics of HTTP verbs: TIER APIs follow the customary definition of HTTP verbs such as GET, PUT, POST, DELETE. In some cases it will be necessary to specify different nuances depending on the resource and the context. – Refer to a specific documentation for what we're adhering to (HTTP 1.1 RFC, SCIM) might need our own overrides at some point

  • 7) Filtering syntax for searches and queries, if supported, follows SCIM section 3.4.2.2

  • 8) Pagination of multiple-entry results, if supported, follows SCIM section 3.4.2.4; Doesn't work well with a complete, large result set, bulk operations...

  • 9) TIER defines standardized elements of response metadata that should accompany any resource representation; look at group member documentation for an example 

  • 10) The request/response data representation will be JSON.
    • In cases where JSON types are not specific enough, TIER schema will specify constraints on JSON string values. E.g., for calendar dates, the JSON type will be string, but the TIER specification will constrain the string values to valid 'calendar dates' per the ISO 8601 definition.

  • 11) The normative form of TIER API specifications will be Swagger (currently at V2); schema is represented how? 

  • 12) The HTTP headers returned in TIER API response bodies are:

    • X-TIER-success: required, boolean, "true" or "false"
      • "true" means the TIER API server successfully handled the request.  Even if the header value is "false" there might be a response body
      • 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 if 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
    • X-TIER-resultCode: required, string, corresponds to the result code in the body.  There should only be a handful of valid response codes for a given request resource and HTTP method
    • X-TIER-requestId: optional, string, unique ID unique URL for the request that can be used for troubleshooting, auditing, or logging
    • X-TIER-responseDurationMillis: optional, integer, number of milliseconds that the server took to process the request.
    • Headers should be named: X-TIER-someName where the last string is camelCase

  • 13) "Users" and "Groups" are the primary resources referred to in this version of the API

    • Resource names should be camel case starting with a capital letter, e.g. /myTierServer/Person/id:abc/Group/groupName:edu:institution:whatever
    • If you have a resource URL with an included sub-resource, the sub-resource must be identified in the path.  I.e. don't do: /User/some:id/role:id  where role is only implied, do /User/some:id/Role/role:id, making Role an explicit sub-resource.

    • 13.5) Users, Groups,....so plural; 

  • 14) Different clients (identified by authenticating credential) might see different resource representations in responses
    • This might be due to the privileges that the clients have on the data
    • This might be due to a server configuration that returns more optional data elements

  • 15) Parameters can be passed in the body of the request or on the URL.  e.g. ?paramName=paramValue

    • Parameter names defined in TIER APIs not found in SCIM must begin with "tier" followed by ".", followed by the desired parameter name.
    • Parameter names should be camel case starting with lower case
    • Parameter values should be camel case starting with lower case
    • Parameter booleans should be "true" or "false"
    • Parameter names and values are case sensitive
    • If a resource definition allows a site to add a local parameter name, that parameter name should begin with the camel case concatenation of the two-level domain name with an underscore at the end. E.g. "wiscEdu_localParameter"
    • If a resource definition allows a site to add a local parameter value, that value should begin with the camel case concatenation of the two-level domain name with an underscore at the end. E.g. "wiscEdu_localValue"  SCIM User and TIER User would be available but each at their own end points.  

  • 16) Response codes should be all in capital letters (possibly including numerals) 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

  • 17) Resources can be identified in various ways which avoids having to do superfluous lookups.  
    • Resources should have a primary identifier.  
      • The value of this identifier should not change.  
      • It should be opaque to allow for renames.  
    • Resources s can be referred to by other unique identifiers as well.  
    • Unique identifiers that are not the primary identifier can change.  
    • The type of identifier is specified in a prefix
      • Prefixes must be alphanumeric. 
      • A colon separates the prefix from the identifier value. 
      • Prefixes cannot contain colons or whitespace.  
      • 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"

      • The TIER-defined prefixes are:

        • id  -  this is the unchanging primary identifier of the object
        • 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)
        • index  - if applicable, this is the numeric index of the object, e.g. the posix ID of the group
        • 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
        • loginId -  if applicable, this will lookup an object by a netId
        • eppn  -  if applicable, this will lookup an object based on the scoped netId or whatever is used for eppn
        • others TBD, will begin with "tier"

        Examples:

  • No labels