Skip to content

Instantly share code, notes, and snippets.

@bsavage

bsavage/gist:6998bf9b43a91aa850ee

Created March 3, 2016 21:11
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save bsavage/6998bf9b43a91aa850ee to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save bsavage/6998bf9b43a91aa850ee to your computer and use it in GitHub Desktop.
Download ZIP
Standards and Guidelines for Designing RESTful APIs in TIER
Raw
gistfile1.txt
<p> </p>
<p> </p>
<ac:structured-macro ac:macro-id="eb18d766-4fc4-4279-8386-62b8f8848a39" ac:name="info" ac:schema-version="1">
<ac:rich-text-body>
<p>This is a consolidation of the work under the headings of "Guidelines for Designing RESTful APIs in TIER" and "TIER API SCIM common elements"</p>
<p>An attempt was made to assimilate discussion resolutions here and point to references where work is ongoing.</p>
</ac:rich-text-body>
</ac:structured-macro>
<p> </p>
<h3 class="conf-macro output-inline">
<strong>Standards and guidelines that apply to all TIER APIs</strong>
</h3>
<p>
<strong>
<br/>
</strong>
</p>
<table>
<tbody>
<tr>
<th>Category</th>
<th>Description of guideline/standard</th>
<th colspan="1">
<span style="color: rgb(0,0,0);">Constraints/exceptions</span>
</th>
<th colspan="1">Supporting work/issues/resources</th>
</tr>
<tr>
<td>
<strong>SCIM Compliance</strong>
</td>
<td colspan="3"> </td>
</tr>
<tr>
<td>API operations</td>
<td>
<span>For all API operations that can be found in SCIM, follow the </span> <a class="external-link" href="https://tools.ietf.org/html/rfc7644">SCIM protocol</a>
</td>
<td colspan="1"> </td>
<td colspan="1">
<ol>
<li>See SCIM at: <a href="https://tools.ietf.org/html/rfc7644">https://tools.ietf.org/html/rfc764</a>3 and <a href="https://tools.ietf.org/html/rfc7644">https://tools.ietf.org/html/rfc7644</a>
</li>
<li>See initial TIER group operations at:<br/>
<a href="https://spaces.internet2.edu/display/DSAWG/Initial+Set+of+TIER+Group+Management+APIs" style="line-height: 1.4285715;">https://spaces.internet2.edu/display/DSAWG<br/>
</a>
<a href="https://spaces.internet2.edu/display/DSAWG/Initial+Set+of+TIER+Group+Management+APIs" style="line-height: 1.4285715;">/Initial+Set+of+TIER+Group+Management+APIs</a> </li>
<li>See also: <a href="https://bugs.internet2.edu/jira/browse/TIERAPI-1">https://bugs.internet2.edu/jira/browse/TIERAPI-1</a>
</li>
</ol>
</td>
</tr>
<tr>
<td colspan="1">Schema</td>
<td colspan="1">
<span>Go beyond the </span> <a class="external-link" href="https://tools.ietf.org/html/rfc7643">SCIM-defined schema</a> <span> to cover additional attributes</span>
</td>
<td colspan="1"> </td>
<td colspan="1">
<p>On making schema compliant and extensible, see:</p>
<p>
<a href="https://spaces.internet2.edu/display/DSAWG/Ignoring+Unrecognized+Schema+Fragments+in+a+Received+Resource+Representation">https://spaces.internet2.edu/display/DSAWG/Ignoring+Unrecognized+<br/>Schema+Fragments+in+a+Received+Resource+Representation</a>
</p>
</td>
</tr>
<tr>
<td colspan="1">Resource types</td>
<td colspan="1">
<span>Follow SCIM </span> <a class="external-link" href="https://tools.ietf.org/html/rfc7643#section-6">Section 6</a> <span> when defining additional resource types</span>
</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="3">
<strong>Requests</strong>
</td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1">HTTP verbs</td>
<td colspan="1">
<span>Customary definition of HTTP verbs (e.g., GET, PUT, POST, DELETE) will be followed.<br/> <br/> </span>
</td>
<td colspan="1">
<span>In</span> <span>some cases it will be <br/>necessary to specify different <br/>nuances in different contexts.</span>
</td>
<td colspan="1">See: <a href="https://www.ietf.org/rfc/rfc2616.txt">https://www.ietf.org/rfc/rfc2616.txt</a>
</td>
</tr>
<tr>
<td colspan="1">URI syntax</td>
<td colspan="1">
<p>Follow REST conventions</p>
</td>
<td colspan="1">
<ol>
<li>
<p>The major version of the client is in the URL: <a href="https://groups.institution.edu/tierGroups/v1">https://groups.institution.edu/tierGroups/v1</a>
</p>
</li>
<li>SCIM will be followed with respect to plurals</li>
</ol>
</td>
<td colspan="1"> </td>
</tr>
<tr>
<td>Resource (URI) syntax</td>
<td>Resource reference syntax</td>
<td>
<ol>
<li>Resource names should be camel case starting with a capital letter.</li>
<li>SCIM will be followed with respect to plurals</li>
<li>If you have a resource that has a sub-resource, then you need to specify that sub-resource.  Do this: <span style="line-height: 1.4285715;">/Users/some:id/Roles/role:id</span>
<span style="line-height: 1.4285715;">  not: </span>/Users/some:id/role:id<br/>e.g. /myTierServer/Users/id:abc/Groups/groupName:edu:institution:whatever</li>
<li>
<p>The major version of the client is in the URL: <a href="https://groups.institution.edu/tierGroups/v1">https://groups.institution.edu/tierGroups/v1</a>
</p>
</li>
</ol>
</td>
<td> </td>
</tr>
<tr>
<td colspan="1">Object references</td>
<td colspan="1">
<p>Objects can be referred to in various ways without having to do superfluous lookups.  </p>
<p>Objects should have a primary identifier.  This identifier should not change.  Therefore it should be opaque to allow for renames.</p>
<p>Objects can be referred to by other unique identifiers as well.  Unique identifiers that are not the primary identifier can change.  </p>
<p>Prefixes specify how the objects are referred to.</p>
</td>
<td colspan="1">
<ol>
<li>
<span style="line-height: 1.4285715;">
<span>Prefixes must be alphanumeric.  These prefixes therefore cannot contain colons or whitespace.</span>
</span>
</li>
<li>
<span style="line-height: 1.4285715;">
<span>It is recommended that institutions use prefixes with part of the prefix related to the institution<br/>(e.g. the pennkey at penn could have a prefix "pennkey")</span>
</span>
</li>
<li>The TIER-defined prefixes are:<ol>
<li>id  -  this is the unchanging primary identifier of the object</li>
<li>name  -  if applicable, this is the system name of the object (e.g. the name which doesn't <br/>change much and which might not be opaque, e.g. the group name)</li>
<li>index  - if applicable, this is the numeric index of the object, e.g. the posix ID of the group</li>
<li>uniqueAttribute  -  this will lookup one object by any of the id or any unique attribute.  if it finds <br/>multiple objects, it will return an error</li>
<li>loginId -  if applicable, this will lookup an object by a netId</li>
<li>eppn  -  if applicable, this will lookup an object based on the scoped netId or whatever<br/>is used for eppn</li>
<li>other prefixes will begin with "tier"</li>
<li>to deal with potential edge cases, a prefix should not contain the delimiter (e.g, ":"), and everything after the actual delimiter should be considered the value</li>
</ol>
</li>
</ol>
<p>Examples:</p>
<p>URL of user by opaque id: <a class="external-link" href="https://people.institution.edu/entities/id:1234567">https://people.institution.edu/entities/id:1234567</a>
</p>
<p>URL of user by netid: <a class="external-link" href="https://people.institution.edu/entities/netId:jmith">https://people.institution.edu/entities/netId:jmith</a>
</p>
<p>URL of groups for a user by eppn: <a class="external-link" href="https://groups.institution.edu/entities/eppn:[email protected]/groups">https://groups.institution.edu/entities<br/>/eppn:[email protected]/groups</a>
</p>
<p>URL of seeing if a user is in a group <a class="external-link" href="https://groups.institution.edu/groups/name:edu:institution:community:employees/members/uniqueAttribute:1234543">https://groups.institution.edu/groups/name:edu:institution:community:employees<br/>/members/uniqueAttribute:1234543</a>
</p>
</td>
<td colspan="1">See recent discussion at bottom of:<br/>
<a href="https://spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+common+elements">https://spaces.internet2.edu/display/DSAWG<br/>/TIER+API+SCIM+common+elements</a> </td>
</tr>
<tr>
<td colspan="1">Searches and queries</td>
<td colspan="1">
<span>Filtering syntax for searches and queries follows SCIM </span> <a class="external-link" href="https://tools.ietf.org/html/rfc7644#section-3.4.2.2">section 3.4.2.2</a>
</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1">Pagination</td>
<td colspan="1">
<span>Follow SCIM </span> <a class="external-link" href="https://tools.ietf.org/html/rfc7644#section-3.4.2.4">section 3.4.2.4 on pagination</a>
</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1">Parameter passing and syntax</td>
<td colspan="1">
<p>Parameters can be passed to resource requests in the body of the POST or as URL parameters (e.g. ?paramName=paramValue)</p>
</td>
<td colspan="1">
<ol>
<li>Parameter names defined in TIER APIs not found in SCIM must begin with "tier" <br/>followed by ".", followed by the desired parameter name.</li>
<li>Parameter names should be camel case starting with lower case.</li>
<li>Parameter values should be camel case starting with lower case.</li>
<li>Parameter booleans should be "true" or "false".</li>
<li>Parameter names and values are case sensitive.</li>
<li>If a resource allows a site to add a parameter name, the site name should begin with the camel case concatenation of the two-level domain name with a period at the end (e.g. "wiscEdu.localParameter").</li>
<li>If a resource allows a site to add a parameter value, the value should begin with the camel case concatenation of the two-level domain name with a period at the end. (e.g. "<a class="external-link" href="http://wisc.edu/" style="line-height: 1.4285715;">wiscEdu</a>.localValue").</li>
</ol>
</td>
<td colspan="1"> </td>
</tr>
<tr>
<td>
<strong>Responses</strong>
</td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td colspan="1">Response format</td>
<td colspan="1">JSON</td>
<td colspan="1">
<ol>
<li>
<span>In some cases we will define</span> <br class="_mce_tagged_br"/> <span>constraints on string values, </span> <br/> <span>e.g. for calendar dates, the JSON </span> <br/> <span>type will be string, but TIER will </span> <br/> <span>constrain the string values to conform</span> <br/> <span> to </span> <span>ISO 8601 </span> <span>'calendar date'</span>
</li>
<li>xml and other formats can be provided by the server but are not required</li>
</ol>
</td>
<td colspan="1"> </td>
</tr>
<tr>
<td>Response content</td>
<td>Representations (such as users, groups)</td>
<td>
<ol>
<li>
<span>Different clients (identified by authenticating credential) might see different responses<br class="_mce_tagged_br"/>
</span>a) This might be due to the privileges that the clients have on the data<br/>b) T<span>his might be due to a server configuration that returns more optional data elements</span> </li>
</ol>
</td>
<td>Example of representation of user in response:<br/>
<a href="https://spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+group+member">https://spaces.internet2.edu/display/DSAWG<br/>/TIER+API+SCIM+group+member</a> </td>
</tr>
<tr>
<td colspan="1">Metadata</td>
<td colspan="1">
<span>Standardized elements of response metadata</span>
</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1">Response codes</td>
<td colspan="1">HTTP response codes will not be overridden but enriched</td>
<td colspan="1">
<p>HTTP response codes are not entirely unambiguous with respect<br/>to all resource operations so supplemental response information will be provided.</p>
<p>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</p>
<p> </p>
</td>
<td colspan="1">
<ol>
<li>
<span style="color: rgb(34,34,34);">TIER discussion thread:<br/>
</span>
<span style="color: rgb(34,34,34);">[tier-api] HTTP response code</span>
</li>
<li>
<span style="color: rgb(34,34,34);">Tracked in: <a href="https://bugs.internet2.edu/jira/browse/TIERAPI-2">https://bugs.internet2.edu/jira/browse/TIERAPI-2</a>
</span>
</li>
<li>
<span style="color: rgb(34,34,34);">Examples of TIER response codes here:<br/>
<a href="https://spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+group+member">https://spaces.internet2.edu/display/DSAWG<br/>/TIER+API+SCIM+group+member</a> </span>
</li>
<li>
<span style="color: rgb(34,34,34);">
<span>See recent discussion at bottom of:</span>
<br/>
<a href="https://spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+common+elements">https://spaces.internet2.edu/display/DSAWG<br/>/TIER+API+SCIM+common+elements</a>
<span> </span>
</span>
</li>
</ol>
</td>
</tr>
<tr>
<td colspan="1">TIER HTTP headers</td>
<td colspan="1">
<ol>
<li>X-TIER-success: required, boolean, true or false</li>
<li>X-TIER-resultCode: required, string, corresponds to the result code in the body.</li>
<li>(optional) X-TIER-requestId: string, unique ID for the request that can be used for troubleshooting, auditing, or logging</li>
<li>(optional) X-TIER-responseDurationMillis: integer, number of milliseconds that the server took to process the request.</li>
</ol>
<p> </p>
</td>
<td colspan="1">
<p>Headers should be named: X-TIER-someName where the last string is lower-case camelcase</p>
<p>Related to numbered items in preceding column:</p>
<ol>
<li>
<p>true means the TIER API server successfully handled the request.  Even if the response is false <br/>there might be a body to parse</p>
<p>Generally this is implemented on the server with exception handling.  If there is an exception <br/>and any database transactions are rolled back then the response is false.</p>
<p>Note that if looking up a resource the HTTP status code might be 404 but X-TIER-success is <br/>still true.</p>
<p>If a batched request is partially successful then this response code should be true if it <br/>can be returned.  The body should give details about the failure.</p>
</li>
<li>
<p>
<span>There should only be a handful of valid response codes for a given request resource <br/>and HTTP method </span>
</p>
</li>
</ol>
<p>Note: If the request requires authentication and none is sent, a 401 HTTP status code will be <br/>returned and there might not be TIER headers since this response could be sent by the web server.</p>
</td>
<td colspan="1"> </td>
</tr>
<tr>
<td>
<strong>Securing APIs</strong>
</td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td colspan="1"> </td>
<td colspan="1">HTTPS</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1"> </td>
<td colspan="1">Techniques for securing API operations are currently external to the API.</td>
<td colspan="1">
<span>(Reference auth types suggested are HTTP Basic and SSL certificates)</span>
</td>
<td colspan="1">
<p>Assumes API is passed the value of the authenticated identity.</p>
</td>
</tr>
<tr>
<td colspan="1">
<strong>API specification</strong>
</td>
<td colspan="1"> </td>
<td colspan="1"> </td>
<td colspan="1"> </td>
</tr>
<tr>
<td colspan="1"> </td>
<td colspan="1">Swagger specification and compliant tools.</td>
<td colspan="1"> </td>
<td colspan="1">
<ol>
<li>See swagger spec:<br/>
<a href="http://swagger.io/specification/" style="line-height: 1.4285715;">http://swagger.io/specification/</a>
</li>
<li>Swagger tools:<br/>
<a href="http://swagger.io/tools/" style="line-height: 1.4285715;">http://swagger.io/tools/</a>
</li>
</ol>
</td>
</tr>
</tbody>
</table>
<p>
<span style="color: rgb(0,0,0);"> <span> </span> </span>
</p>
<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block">
<p> </p>
</div>
<p> </p>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment