You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This is a wiki for the standard API for Groups, Subjects, Permissions

This is a RESTful API which is initially focused on HTTP/JSON.

Standards

  • Fields can be marked as
    • Mandatory: implementors must implement this field
    • Default: when requesting the resource, these fields will be returned.  Other fields can be retrieved if they are requested
  • Timestamps are ISO 8601, e.g.: 2012-10-04T03:10Z or 2012-10-04
  • Request/response wrapper.  Requests and response are wrapper in an object wrapper.  Responses have a responseMeta field which has the following fields:
    • success (default/mandatory): true/false, if the request was successfully validated.  e.g. if it is a hasMember request, then this is true if the group and entity are valid and resolvable
    • serviceRootUrl (default/mandatory): is the URL of the service up to the first resource.  e.g. if this is where the groups are: https://groups.school.edu/groupsService/standardApi/groups, then the serviceRootUrl is: https://groups.school.edu/groupsService/standardApi
    • serverVersion (default/mandatory): is the dot release of the server, e.g. 1.4
    • resultCode (default/mandatory): is the status code of the request, specific to the resource/method
    • warnings: if the servers whats to give text warnings for the client to log, this is where they go
    • millis: the milliseconds spent on the server to process the request
    • requestProcessed: echo the request that was processed, in free-form text
    • serverType(mandatory): some string representing the implementation vendor of the API.  e.g. "Grouper Standard API"
    • responseTimestamp(mandatory): timestamp of when the response was generated 
  •  
  •  

Versioning

The version of the API is an integer which is sent in the URL.  If the API is changed in a backwards compatible way (e.g. extra fields which do not change names or structure), then the version number doesn't change. However, there is also a dot version number which includes another integer for the revision number which is changed whenever the API is changed in a backwards compatible way.  The server dot version is sent in the response metadata. 

  • No labels