RESTful UpMan API

The Unity UpMan REST API may be exposed (or disabled) as a regular Unity endpoint. See the main Unity documentation for endpoints configuration details.

All paths must be naturally prefixed with the server’s base URL, endpoint deployment’s path (as configured) and API version (currently there is only one). Example query path can be similar to:

https://unity.example.com/rest-upman/v1/projects/PROJECT-ID

1. Projects

1.1. Create project

@Path("/projects")
@POST

Adds a new project.

If projectId is null or skipped, it will be auto generated.

Example input:

{
    "projectId": "my-project-id",
    "public": false,
    "displayedName": {
        "en": "displayedName"
    },
    "description": {
        "en": "description"
    },
    "logoUrl": "https://www.myservice.org/logo",
    "enableSubprojects": true,
    "readOnlyAttributes": []
}

Example output:

{
    "id": "my-project-id"
}

1.2. Update project

@Path("/projects/{project-id}")
@PUT

Updates the project.

Example input:

{
    "public": false,
    "displayedName": {
        "en": "displayedName"
    },
    "description": {
        "en": "description"
    },
    "logoUrl": "https://www.myservice.org/logo",
    "enableSubprojects": true,
    "readOnlyAttributes": []
}

1.3. Remove project

@Path("/projects/{project-id}")
@DELETE

Removes the given project.

1.4. Get project

@Path("/projects/{project-id}")
@GET

Retrieves the given project.

Example output:

{
    "project-id": "projectId",
    "public": false,
    "displayedName": {
        "en": "displayedName"
    },
    "description": {
        "en": "description"
    },
    "logoUrl": "https://www.myservice.org/logo",
    "enableSubprojects": true,
    "readOnlyAttributes": [],
    "registrationForm": "registrationFormName",
    "signUpEnquiry": "signUpEnquiryName",
    "membershipUpdateEnquiry": "membershipUpdateEnquiryName"
}

1.5. Get projects

@Path("/projects")
@GET

Retrieves all projects.

Example output:

[
	{
	    "project-id": "projectId",
	    "public": false,
	    "displayedName": {
	        "en": "displayedName"
	    },
	    "description": {
	        "en": "description"
	    },
	    "logoUrl": "https://www.myservice.org/logo",
	    "enableSubprojects": true,
	    "readOnlyAttributes": [],
	    "registrationForm": "registrationFormName",
	    "signUpEnquiry": "signUpEnquiryName",
	    "membershipUpdateEnquiry": "membershipUpdateEnquiryName"
	}
]

2. Policy documents

2.1. Add policy document

@Path("/projects/{project-id}/policyDocuments")
@POST

Adds a new project policy document. ContentType can be one of "LINK" or "EMBEDDED"

Example input:

{
    "name": "Policy1",
    "displayedName": {
        "en": "Policy1"
    },
    "mandatory": false,
    "contentType": "EMBEDDED",
    "content": {
        "en": "Policy1"
    }
}

2.2. Update policy document

@Path("/projects/{project-id}/policyDocuments")
@QueryParam("incrementRevision")
@PUT

Updates the given policy document. If query parameter "incrementRevision" is set to true, update increment revision, and re-acceptance will be needed. ContentType can be one of "LINK" or "EMBEDDED"

Example input:

{
    "id": 1,
    "name": "Policy1",
    "displayedName": {
        "en": "Policy1"
    },
    "mandatory": false,
    "contentType": "EMBEDDED",
    "revision": 1,
    "content": {
        "en": "Policy1"
    }
}

2.3. Remove policy document

@Path("/projects/{project-id}/policyDocuments/{policy-id}")
@DELETE

Removes the given project policy document.

2.4. Get policy document

@Path("/projects/{project-id}/policyDocuments/{policy-id}")
@GET

Returns the given policy document.

Example output:

{
    "id": 1,
    "name": "Policy1",
    "displayedName": {
        "en": "Policy1"
    },
    "mandatory": false,
    "contentType": "EMBEDDED",
    "revision": 1,
    "content": {
        "en": "Policy1"
    }
}

2.5. Get policy documents

@Path("/projects/{project-id}/policyDocuments")
@GET

Returns all project policy documents.

Example output:

[
    {
        "id": 1,
        "name": "Policy1",
        "displayedName": {
            "en": "Policy1"
        },
        "mandatory": false,
        "contentType": "EMBEDDED",
        "revision": 1,
        "content": {
            "en": "Policy1"
        }
    },
    {
        "id": 2,
        "name": "Policy2",
        "displayedName": {
            "en": "Policy2"
        },
        "mandatory": false,
        "contentType": "EMBEDDED",
        "revision": 1,
        "content": {
            "en": "Policy2"
        }
    }
]

3. Forms

3.1. Create registration form

@Path("/projects/{project-id}/registrationForm")
@QueryParam("autogenerate")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new project registration form specified by the JSON object passed as request body. The optional boolean autogenerate query parameter can be used then request body can be skipped and form will be autogenerate for project

3.2. Update registration form

@Path("/registrationForm")
@QueryParam("ignoreRequests")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing project registration form. The body of the request should include a JSON description of a form, as during form creation. The only difference is that this method expects existing form id. The optional boolean ignoreRequests query parameter can be used to force form update even if it has attached pending requests. Beware, however, that those requests can easily become invalid.

3.3. Remove registration form

@Path("/projects/{project-id}/registrationForm")
@QueryParam("dropRequests")
@DELETE

Removes project registration form. An optional query parameter dropRequests can be provided with a boolean value, to control whether the form should be removed also if it has pending requests (the requests will be removed with the form).

3.4. Get registration form

@Path("/projects/{project-id}/registrationForm")
@GET

Returns a project registration form. The syntax is complex and is not provided here.

3.5. Create signup enquiry form

@Path("/projects/{project-id}/signUpEnquiry")
@QueryParam("autogenerate")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new signup enquiry form specified by the JSON object passed as request body. The optional boolean autogenerate query parameter can be used then request body can be skipped and form will be autogenerate for project

3.6. Update signup enquiry form

@Path("/projects/{project-id}/signUpEnquiry")
@QueryParam("ignoreRequests")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing signup enquiry form. The body of the request should include a JSON description of a form, as during form creation. The only difference is that this method expects existing form id. The optional boolean ignoreRequests query parameter can be used to force form update even if it has attached pending requests. Beware, however, that those requests can easily become invalid.

3.7. Remove signup enquiry form

@Path("/projects/{project-id}/signUpEnquiry")
@QueryParam("dropRequests")
@DELETE

Removes project signup enquiry form. An optional query parameter dropRequests can be provided with a boolean value, to control whether the form should be removed also if it has pending requests (the requests will be removed with the form).

3.8. Get signup enquiry form

@Path("/projects/{project-id}/signUpEnquiry")
@GET

Returns a project singup enquiry form. The syntax is complex and is not provided here.

3.9. Create membership update enquiry form

@Path("/projects/{project-id}/membershipUpdateEnquiry")
@QueryParam("autogenerate")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new membership update enquiry form specified by the JSON object passed as request body. The optional boolean autogenerate query parameter can be used then request body can be skipped and form will be autogenerate for project

3.10. Update signup enquiry form

@Path("/projects/{project-id}/membershipUpdateEnquiry")
@QueryParam("ignoreRequests")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing membership update enquiry form. The body of the request should include a JSON description of a form, as during form creation. The only difference is that this method expects existing form id. The optional boolean ignoreRequests query parameter can be used to force form update even if it has attached pending requests. Beware, however, that those requests can easily become invalid.

3.11. Remove membership update enquiry form

@Path("/projects/{project-id}/membershipUpdateEnquiry")
@QueryParam("dropRequests")
@DELETE

Removes project membership update enquiry form. An optional query parameter dropRequests can be provided with a boolean value, to control whether the form should be removed also if it has pending requests (the requests will be removed with the form).

3.12. Get membership update enquiry form

@Path("/projects/{project-id}/membershipUpdateEnquiry")
@GET

Returns a project membership update enquiry form. The syntax is complex and is not provided here.

4. Members

4.1. Add member

@Path("/projects/{project-id}/members/{userId}")
@POST

Adds a user to the specified project.

Property userId should be provided as user’s email.

4.2. Remove member

@Path("/projects/{project-id}/members/{userId}")
@DELETE

Removes a user from the specified project.

4.3. Get member

@Path("/projects/{project-id}/members/{userId}")
@GET

Returns the specified user. Example output:

{
    "email": "[email protected]",
    "role": "manager",
    "attributes": [{
        "name": "attribute-name",
        "values": ["val1", "val2"]
    }]
}

4.4. Get members

@Path("/projects/{project-id}/members")
@GET

Returns all project users. Example output:

[
	{
	    "email": "[email protected]",
	    "role": "manager",
	    "attributes": [{
	        "name": "attribute-name",
	        "values": ["val1", "val2"]
	    }]
	}
]

4.5. Get member authorization role

@Path("/projects/{project-id}/members/{userId}/role")
@GET

Returns user’s project authorization role. Property role can be one of (manager, projectsAdmin, regular) Example output:

{
    "role": "manager"
}

4.6. Set member authorization role

@Path("/projects/{project-id}/members/{userId}/role")
@PUT

Updates user’s authorization role. Property role can be one of (manager, projectsAdmin, regular).

Example output:

{
    "role": "manager"
}