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.

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
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
Fields should be named with camelcase. e.g. thisIsSomeField names should be compatible with java variable names
Any URI fields should end 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,                 (record 0-indexed to start with... second page would be offset 100)
    "count": 100,                (number of records to return)
    "sortField": "displayName",  (field name is dependent on the search)
    "ascending": true,
    "count": 534                 (total number of records)
  }

To put paging in the request, use these params: resource?paging.offset=5&paging.sortField=name&paging.ascending=false&paging.count=200
- Note: if the count is too high the server can override the request and lower the count. However, the server should support at least a count 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 in the object
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
Act as can be specified with: actAs=netId:jsmith (or whatever URI for the subject). The server will determine if that is allowed.
Resources must end in the format requested. Possible formats are json and xml. e.g. https://groups.institution.edu/groupsApp/groupsApi/v1/groups.json or https://groups.institution.edu/groupsApp/groupsApi/v1/groups.xml

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 resources

https://groups.institution.edu/groupsApp/groupsApi

Note: This always returns JSON... with pointers to the various formats

LastModified will be mandated from the API, when the API changes

{
  "_meta": {
    "lastModified":"2012-10-04T03:10Z",
    "selfUri":"https://groups.institution.edu/groupsApp/groupsApi"
  }
  "jsonDefaultUri": "https://groups.institution.edu/groupsApp/groupsApi.json",
  "xmlDefaultUri": "https://groups.institution.edu/groupsApp/groupsApi.xml"
}

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

Page tree