Grouper Standard API

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

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

Discussion items

Absolute URLs vs relative URLs
Path separators

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 wrap objects which are the real responses, e.g. they are a field in the response 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/v1/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
- serverMillis: 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
Extra fields are requested with the "fields" parameter. e.g. "fields"="responseMeta.default,defaultResource.default"
If requesting extra fields, request with the path and field name. e.g. to get the number of millis that it took to process on the server, ask for this field: "fields"="responseMeta.serverMillis"
If requesting all extra field, use the "all" field. e.g. responseMeta.all
If requesting the default field, use the "default" field. e.g. responseMeta.default will return all default fields
If requesting extra fields, then the default fields arent shown unless requested
If unexpected fields are added to the request or reponse, it should not break the processing of the request or response
Any URL field should end in "Url". e.g. membersUrl, Note the URL is absolute, though can be converted to relative by considering the responseMeta.serviceRootUrl field

If the request returns paged resources, then there is a paging field returned (pageNumber is 0 indexed):

"paging": {
    "pageNumber": 0,
    "pageSize": 100,
    "sortString": "displayName",
    "ascending": true,
    "totalResults": 534
  }

To put paging in the request, use these params: resource?paging.pageNumber=5&paging.sortString=name&paging.ascending=false&paging.pageSize=200
- Note: if the pageSize is too high the server can override the request and lower the pageSize. However, the server should support at least a pagesize of 1000
The folder path separator is colon. If colons are in the parts of the name, URL escape them. Group names need to be escaped for the group name, which can be put in the URL for certian operations
Method is the HTTP method, unless the HTTP header: X-HTTP-Method-Override: DELETE is set, which has a value of a valid method, e.g. GET, PUT, POST, DELETE
If there are extra attributes, these in an extensions map

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.

Default resource

The default resource has urls to the various default resources, GET only. e.g. GET for https://groups.institution.edu/groupsApp/groupsApi/v1/

Response:

{
  "defaultResource": {
    "groupsUrl": "https://groups.institution.edu/groupsApp/groupsApi/v1/groups",
    "foldersUrl": "https://groups.institution.edu/groupsApp/groupsApi/v1/folders",    "entitiesUrl": "https://groups.institution.edu/groupsApp/groupsApi/v1/entities",
    "permissionsUrl": "https://groups.institution.edu/groupsApp/groupsApi/v1/permissions"  },
  "responseMeta": {
    "success": true,
    "serviceRootUrl": "https://groups.institution.edu/groupsApp/groupsApi",
    "serverVersion": "1.4",
    "resultCode": "SUCCESS"
  }
}

Example with additional

Groups resource

The groups resource: https://groups.institution.edu/groupsApp/groupsApi/v1/groups

This is GET only. It will return a list of groups, and it might page the results based on server settings. Sample response

{
  "groups": [
    {
      "id": "123abc",
      "name": "a:b:c",
      "displayName": "A:B:C",
      "description": "This is the description",
      "status": "active"
    },
    {
      "id": "124abd",
      "name": "a:b:d",
      "displayName": "A:B:D",
      "description": "This is the description4",
      "status": "active"
    }
  ],
  "responseMeta": {
    "success": true,
    "serviceRootUrl": "https://groups.institution.edu/groupsApp/groupsApi",
    "serverVersion": "1.4",
    "resultCode": "SUCCESS"
  }
}

Filter the results:https://groups.institution.edu/groupsApp/groupsApi/v1/groups?groups.status=active
or: groups.name=a:b:*
or: groups.parentFolder=a:b&groups.parentFolderScope=ONE_LEVEL (or ALL_IN_SUBTREE)

Individual group resource

The group resource: https://groups.institution.edu/groupsApp/groupsApi/v1/groups/a:b

This resource is available for GET, PUT, POST, DELETE

GET Sample response:

{
  "group":
    {
      "id": "123abc",
      "name": "a:b:c",
      "displayName": "A:B:C",
      "description": "This is the description",
      "status": "active"
    },
  "responseMeta": {
    "success": true,
    "serviceRootUrl": "https://groups.institution.edu/groupsApp/groupsApi",
    "serverVersion": "1.4",
    "resultCode": "SUCCESS"
  }
}

success is true if the URL is correct up until the group name part.

PUT Sample request:

{
  "group":
    {
      "id": "123abc",
      "name": "a:b:c",
      "displayName": "A:B:C",
      "description": "This is the description",
      "status": "active"
    }
}

sdf

Page tree