Authorization 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.

Error rendering macro 'children'

null

Open questions

1. Changed requestMeta to responseMeta since we might have metadata from client to server (request), where this is from server to client (response)

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:10:14.123Z note: no other 8601 representations are allowed.
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 top level fields: meta, responseMeta:
- meta (metadata about the resource)
  - lastModified (default, mandatory): timestamp when the resource was modified
  - selfUri (default, mandatory): URI to the current resource, includes URL params which are expected by server (not authn params etc)
  - structureName: name of the struct which is returned. This might be different if there is an error
- responseMeta : metadata about this particular request/response that goes from server to client
  - 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
  - httpStatusCode: number of the HTTP status code
Extra fields are requested with the "fields" parameter. e.g. fields=name,id&extraFields=service,responseMeta.millis
If requesting all extra fields, use the "all" param. e.g. fields=all&extraFields=all or fields=all&extraFields=responseMeta.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 ?method=DELETE is set, which has a value of a valid method, e.g. GET, PUT, POST, DELETE. Case insensitive on value
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/authzStandardApi/v1/groups.json or https://groups.institution.edu/groupsApp/authzStandardApi/v1/groups.xml
Charset of the values is utf8
Escaping of group names should be URL encoding until we think of a better way
Names should be uri's. e.g. group name could be name:a:b:c
HTTP params are single valued, if there are two values for one param it is an error
If an HTTP param is not expected, it should give a warning
Fields and http params should not start with underscore, they should be alphanumeric and uncontroversial so they can be processed by various languages/formats
Responses should be indented if this param is passed: ?indent=true is passed
Boolean HTTP params can be: true|false or t|f or yes|no or y|n case insensitive

TODO

Discuss history of memberships

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://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi?indent=true

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

LastModified will be mandated from the API, when the API changes, or when the server has restarted

{
  "asasDefaultResource":{
    "jsonDefaultUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi.json",
    "xmlDefaultUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi.xml"
  },
  "meta":{
    "lastModified":"2012-11-04T09:57:03.541Z",
    "selfUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi?indent=true",
    "statusCode":"SUCCESS",
    "structureName":"defaultResourceContainer",
    "success":true
  },
  "responseMeta":{
    "httpStatusCode":200,
    "millis":274
  },
  "serviceMeta":{
    "serverVersion":"1.0",
    "serviceRootUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi"
  }
}

The default resource has urls to the various default resources, GET only. e.g.

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi.json?indent=true

{
  "asasDefaultVersionResource":{
    "serverType":"Grouper WS 2.0.1",
    "v1Uri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1.json"
  },
  "meta":{
    "lastModified":"2012-11-04T09:57:03.541Z",
    "selfUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi.json?indent=true",
    "statusCode":"SUCCESS",
    "structureName":"defaultVersionResourceContainer",
    "success":true
  },
  "responseMeta":{
    "httpStatusCode":200,
    "millis":15
  },
  "serviceMeta":{
    "serverVersion":"1.0",
    "serviceRootUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi"
  }
}

GET https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1.json?indent=true

{
  "asasVersionResource":{
    "entitiesUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/entities.json",
    "foldersUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/folders.json",
    "groupsUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/groups.json",
    "permissionsUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/permissions.json"
  },
  "meta":{
    "lastModified":"2012-11-04T09:57:03.541Z",
    "selfUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1.json?indent=true",
    "statusCode":"SUCCESS",
    "structureName":"versionResourceContainer",
    "success":true
  },
  "responseMeta":{
    "httpStatusCode":200,
    "millis":11
  },
  "serviceMeta":{
    "serverVersion":"1.0",
    "serviceRootUri":"https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi"
  }
}

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1.xml?indent=true

<?xml version="1.0" encoding="UTF-8"?>
<edu.internet2.middleware.authzStandardApiServer.corebeans.AsasVersionResourceContainer>
  <asasVersionResource>
    <entitiesUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/entities.xml</entitiesUri>
    <foldersUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/folders.xml</foldersUri>
    <groupsUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/groups.xml</groupsUri>
    <permissionsUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1/permissions.xml</permissionsUri>
  </asasVersionResource>
  <meta>
    <lastModified>2012-11-04T09:57:03.541Z</lastModified>
    <selfUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi/v1.xml?indent=true</selfUri>
    <statusCode>SUCCESS</statusCode>
    <structureName>versionResourceContainer</structureName>
    <success>true</success>
  </meta>
  <responseMeta>
    <httpStatusCode>200</httpStatusCode>
    <millis>614</millis>
  </responseMeta>
  <serviceMeta>
    <serverVersion>1.0</serverVersion>
    <serviceRootUri>https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/authzStandardApi</serviceRootUri>
  </serviceMeta>
</edu.internet2.middleware.authzStandardApiServer.corebeans.AsasVersionResourceContainer>

sdf

Groups resource

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

params: paging : ?paging.offset=5&paging.sortField=name&paging.ascending=false&paging.count=200

If there are no params, then it will return the first 100 groups in a page sorted ascending by name. if you pass the param paging.enabled=false, it is a hint to not page. However, there may be a limit on the server to enforce mandatory limits. Generally this is a large number e.g. greater than 1000 records.

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",
      "uri": "https://groups.institution.edu/authzStandardApi/authzStandardApi/groups/"
    },
    {
      "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/authzStandardApi",
    "serverVersion": "1.4",
    "resultCode": "SUCCESS"
  }
}

Filter the results:https://groups.institution.edu/groupsApp/authzStandardApi/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/authzStandardApi/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/authzStandardApi",
    "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/authzStandardApi/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/authzStandardApi",
    "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

Child pages