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
- top level: error (error code), error_description (free form), error_uri, status, warning, success
- Fields can be marked as
- Mandatory: implementors must implement this field
- Default: when searching for the resource, these fields will be returned. All fields are returned if the resource is requested. If the user cant access one of the subresources, it is still returned (non admins see the admin URI)
- 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 _service (top level) field which has the following fields, _meta, _requestMeta:
- _service (metadata about the service)
- serviceRootUri (mandatory) : e.g. https://groups.school.edu
- serverVersion (mandatory) : e.g. 1.4, this is the point in time version of the spec which is implemented
- serverType (mandatory) : e.g. Grouper WS Standard API v2.1.14
- _meta (metadata about the resource)
- lastModified (default, mandatory): timestamp when the resource was modified
- selfUri (default, mandatory): URI to the current resource
- _requestMeta : metadata about this particular resource
- responseTimestamp (mandatory): the timestamp that this was sent from the server (at the end of the processing)
- millis (mandatory): number of milliseconds that the server took in processing this request
- requestProcessed (mandatory): freeform text about the request that the server processed, when debugging to make sure the server is processing the right params
- _service (metadata about the service)
- Extra fields are requested with the "fields" parameter. e.g. fields=name,id&extraFields=_service,_requestMeta.millis
- If requesting all extra fields, use the "all" param. e.g. fields=all&extraFields=all or fields=all&extraFields=_requestMeta.all
- If requesting the default fields, use the "default" field. e.g. fields=default will return the 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", any URI should edit in Uri, unless it is a standard (e.g. oauth). 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):
"_meta": { "offset": 0, "count": 100, "sortField": "displayName", "ascending": true, "count": 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
- POST can take a param: createIfNotExist=true for create if not exist
- 401 means you arent authenticated, 403 means you are authenticated and you arent allowed
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 (create) Sample request https://groups.institution.edu/groupsApp/groupsApi/v1/groups/a:b :
{ "group": { "name": "a:b:c", "displayName": "A:B:C", "description": "This is the description", "status": "active" } }
Response 201 for created, 409 for already exists (resultCode: ERROR_ALREADY_EXISTS):
{ "responseMeta": { "success": true, "serviceRootUrl": "https://groups.institution.edu/groupsApp/groupsApi", "serverVersion": "1.4", "resultCode": "SUCCESS_CREATED" } }
POST (update)
Folders collection
PUT /folders/foo
PUT /folders/foo:bar
Special name for top level folder ":"
Folder separator is :
Individual folder resource
id
name
displayName
description
parentUri
folderAdminsUri
folderCreatorsUri
sdf