RFC 7642, SCIM Definitions, Overview,

Concepts, and Requirements

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

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

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

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 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

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")

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.

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

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

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

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

1. See swagger spec:
   http://swagger.io/specification/
2. Swagger tools:
   http://swagger.io/tools/

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".

tierCanonicalLocation