This document lists all Middleware REST API operations and describes how to perform them in terms of required and optional inputs and expected outputs. All operations follow a few simple rules:
-
Most requests require client authentication (HTTP Bearer, client TLS, or HTTP Basic)
-
The content type of all responses is application/json
-
Use the appropriate content type for requests that contain entity bodies
-
Content-Type: application/x-www-form-urlencoded
for POST -
Content-Type: application/json-patch+json
for PATCH
-
-
Query result sort order varies by operation but strives for "natural sort order"
-
20x status on success
-
40x status on client errors (aka "Your Bad")
-
50x status on server errors (aka "Our Bad")
Please see the ED REST API Reference for high-level topics such as conventions, authentication, and available resources.
Operations on Resources
Resources can be created, retrieved, updated, and deleted by varying the HTTP method used in an HTTP request:
-
GET - fetch a resource by ID or query for multiple resources (see subsequent section)
-
POST - create a new resource
-
PATCH - update a resource with merge semantics
-
DELETE - delete a resource
A GET request to the resource collection URI with query parameters is used for a bulk query while a GET to the resource URI is used to fetch a single resource. The following code sample demonstrates the distinction:
# Get a list of Chemistry groups using a "starts with" query and sort results by uugid field
curl $BASE_URL/v1/groups?uugid=chemistry.*&sort=uugid -H"Authorization: Bearer $TOKEN"
# Get the PID account for user hizzy
curl $BASE_URL/v1/accounts/hizzy/pid -H"Authorization: Bearer $TOKEN"
Response Codes
Code | Description |
---|---|
200 |
Successful request that contains a response body. Typical result for fetch and query operations. |
201 |
Successful request that created a new resource. Typical result for POST operations. |
204 |
Successful request that does not contain any content. Typical result for DELETE operations. |
400 |
Client provided invalid data or data that violates a policy. |
401 |
Invalid credentials. |
403 |
Client does not have permission to perform requested operation. |
404 |
The requested resource could not be found. |
409 |
The requested resource already exists. |
429 |
Exceeded some predefined limit; e.g. number of requests, value on a resource. |
Querying for Resources
Querystring parameters are used for selecting and limiting bulk query results; these are particular to each type of resource and are discussed in detail for each operation on a resouce. Query parameters are canonically lowercase in keeping with REST API usage guideline #2. As a general rule, the fields that would be expected to be used for searching are supported for searching; for example, selecting groups by manager role or selecting persons by department/organizational unit.
Multiple fields may specified for selecting and filtering bulk queries, and they are combined into a single logicial filter expression as follows:
-
Distinct fields are combined with an AND expression unless otherwise noted (e.g. group roles)
-
Repeat occurrences of the same field are combined with an OR expression
An example should clarify the behavior. Suppose a client wishes to search for all groups that start with either chemistry.nmr or chemistry.chromatography and are managed or administered by user bob. A GET request to the following URL would produce the desired set of groups:
curl $BASE_URL/v1/group?uugid=chemistry.nmr*&uugid=chemistry.chromatography*&manager=bob&administrator=bob \
-H"Authorization: Bearer $TOKEN"
It’s important to note that group roles have OR semantics, so the distinct manager and administrator fields combine as needed to query for groups in which bob is in either role.
Query Result Pagination
Most query-type endpoints support fetching results in batches of arbitrary size. There are two parameters to control the page and number of results returned: page and size. Pagination parameters are optional, but at least size must be provided when using this facility. Sorting is also supported when using pagination.
Path | Type | Optional | Description |
---|---|---|---|
page |
Integer |
true |
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
size |
Integer |
false |
Size of the page you want to retrieve. Must be greater than 0. |
sort |
String |
true |
How the results should be sorted. Multiple |
Creating a New Resource
The POST method MUST be used for resource creation by making a request to the resource collection URI. All parameters used to create a new resource are provided via application/x-www-form-urlencoded. The following example demonstrates resource creation:
# Create group chemistry.chromatographers, which requires both an administrator and contact
payload = {
'uugid': 'chemistry.chromatographers',
'contact': 'connie',
'administrator': 'albert'
}
headers['Content-Type'] = 'application/x-www-form-urlencoded'
# Response contains empty body and resource URI in Location header
response = requests.post(base_url + '/v1/groups', headers=headers, data=payload)
resource_uri = response.headers['Location']
When a resource is created, a 201 Created response is returned with the newly-created resource URI in the Location response header. A separate request to that URI should be made to fetch the new entity.
Error Handling
In the case of an error response, an error document is provided in the response body that provides details on the error(s) that caused the operation to fail. The following code snippets provide examples of single and multiple error cases.
Single Error Example
{
"code": 400,
"type": "PidStateException",
"message": "PID must be in the 'To Be Released' state before it can be removed"
}
Multiple Error Example
{
"code": 400,
"type": "MultiErrorException",
"message": "BannerPIDM(12345)::Incomplete person update due to errors.",
"details": [
{
"label": "Address(BannerAddressType(PR):BannerPhoneType(PR))",
"message": "Invalid syntax for phone number: 95551939440. Phone numbers must contain only digits and be exactly 10 digits long.",
"type": "AddressInputException"
},
{
"label": "Address(BannerAddressType(MA))",
"message": "Invalid syntax for mailStop: abcd. Mail stops must contain only digits and be exactly 4 digits long.",
"type": "AddressInputException"
}
]
}
The items in the details collection may be objects or strings. In the case of an object, both message and type fields are always present; label is optional.
Date Handling
Date fields are represented as ISO 8601 date strings of the format yyyy-MM-dd’T’hh:mm:ssX
, where X is the offset in
+/-hh:mm
syntax. Dates are always reported in the America/New_York time zone where the main Virginia Tech campus
resides, which allows clients to ignore the time zone when they are in the same locale and thereby simplify
date handling.
Some examples of dates provided by GET operations:
-
2016-11-30T07:30:01-05:00 (07:30:01AM November 30, 2016 EST)
-
2017-01-01T00:01:20-05:00 (12:01:20AM January 1, 2017 EST)
-
2017-05-05T17:45:15-04:00 (5:45:15PM May 5, 2017 EDT)
Clients SHOULD provide dates with a time zone when setting dates; if the time zone is omitted, then the America/New_York time zone is assumed. All of the following may be used to indicate the date 12:30:00PM January 1, 2017 EST:
-
2017-01-01T12:30:00
-
2017-01-01T12:30:00-05:00
-
2017-01-01T07:30:00Z
Clients MAY provide dates as an integer for convenience, which will be treated as a Unix timestamp measured in seconds
since 1970-01-01T00:00:00Z
. Note that this may produce unexpected results as the time will be converted by the system
to America/New_York time, resulting in times that are off by 4 or 5 hours unless care is taken to accommodate for time
zones on the client system. In many cases, however, such rough accuracy is acceptable when handling expiration dates and
similar data elements in the Enterprise Directory.
Account Resource API
Create VT
POST /v2/accounts
Creates a new Virginia Tech account.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Virginia Tech ID number of the person who will own the account. |
|
false |
Account username. |
|
false |
Account password. |
|
true |
Flag to determine if the account credential should be synchronized to other systems. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts' -i -X POST \
-d 'vtid=923456781&username=alice&password=Th3P%40ssword%21&synchronize=true'
Example Response
POST /v2/accounts HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 72
vtid=923456781&username=alice&password=Th3P%40ssword%21&synchronize=true
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 103
{
"type" : "PolicyException",
"code" : 400,
"message" : "User is not eligible for a VT account"
}
Invite Guest
POST /v2/accounts
Invites a guest to create an account by creating an account in UNCREDENTIALED
state, then sending an email invitation with a link to the application complete the setup process. The link includes an authentication token that is used to prove ownership of the email account to which the invitation was sent; the destination email address is the identifier of the guest account.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Recipient of the invitation. |
|
true |
Username of the account that initiated the invitation. |
|
true |
Personalization message to be included in the invitation email. |
|
true |
Zero or more pipe-delimited key-value pairs that will be added as metadata in the token. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts' -i -X POST \
-d 'email=blueberry%40example.com&inviter=inslee&message=Welcome+blue%21'
Example Response
POST /v2/accounts HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68
email=blueberry%40example.com&inviter=inslee&message=Welcome+blue%21
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid metadata key/value pair"
}
Fetch
GET /v2/accounts/{identifier}
Fetches the account with the given unique identifier - either a Username
or an Email
.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of account to fetch. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched account resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/alicesocial?with=all' -i -X GET
Example Response
GET /v2/accounts/alicesocial?with=all HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Query
GET /v2/accounts
Fetches a collection of account resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Identifier (username / email address) of the account |
|
|
Type of account |
|
|
UID identifier of the User owning the account |
|
|
Zero or more optional sections of fields to include in fetched account resources. |
|
|
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
|
|
Size of the page you want to retrieve. Must be greater than 0. |
|
|
How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts?username=the_*&page=3&size=3&sort=checkupDate%2Cdesc&sort=_identifier%2Casc' -i -X GET
Example Response
GET /v2/accounts?username=the_*&page=3&size=3&sort=checkupDate%2Cdesc&sort=_identifier%2Casc HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Recovery Option
POST /v2/accounts/{identifier}/recovery_options
Adds a new recovery option or updates an existing option with the given type.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of the account that will own the recovery option being set. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Type of recovery option to set. Must be one of: [ GOOGLE, OTP2SMS, OTP2VOICE, YAHOO ] |
|
false |
Information required to use the recovery option, such as phone number for OTP2SMS. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/with-new-otp2sms/recovery_options' -i -X POST \
-d 'type=otp2sms&endpoint=5551234567'
Example Response
POST /v2/accounts/with-new-otp2sms/recovery_options HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 32
type=otp2sms&endpoint=5551234567
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/sasquatch/recovery_options' -i -X POST \
-d 'type=google&endpoint=222222222222222222222'
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 150
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'bad_type'. Valid types: [ OTP2SMS, OTP2VOICE, GOOGLE, YAHOO ]"
}
Remove Recovery Option
DELETE /v2/accounts/{identifier}/recovery_options/{type}
Deletes the given type of recovery option from the account.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of the account. |
|
Type of recovery option to remove. Must be one of: [ GOOGLE, OTP2SMS, OTP2VOICE, YAHOO ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/remove-otp2sms/recovery_options/OTP2SMS' -i -X DELETE
Example Response
DELETE /v2/accounts/remove-otp2sms/recovery_options/OTP2SMS HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 150
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'bad_type'. Valid types: [ OTP2SMS, OTP2VOICE, GOOGLE, YAHOO ]"
}
Verify Recovery Options
POST /v2/accounts/{identifier}/recovery_options/verify
Verifies the recovery options and updates the checkup date for the given account.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of the account to verify. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/verify-ops-pos/recovery_options/verify' -i -X POST
Example Response
POST /v2/accounts/verify-ops-pos/recovery_options/verify HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Change Password
POST /v2/accounts/{identifier}/password/change
Resets the passphrase for an account. Invokers of this endpoint are required to authenticate the user performing the reset. No authentication is performed by this method.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of account to change. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
New password for the account. |
|
false |
Token or old password used to authenticate before changing the password. |
|
false |
Type of credential. Must be one of: [ GOOGLE, PASSWORD, TOKEN ] |
|
true |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/alice/password/change' -i -X POST \
-d 'new=1B%40dPassword1%21&credential=hKlBlOXm4t2pihzXxm57b22zUuo&type=token&synchronize=true'
Example Response
POST /v2/accounts/alice/password/change HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 89
new=1B%40dPassword1%21&credential=hKlBlOXm4t2pihzXxm57b22zUuo&type=token&synchronize=true
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Account with ID alice not found"
}
Add Token
POST /v2/accounts/tokens
Generates an TokenScope#AUTHENTICATION
scoped token for the account that is the security principal.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
true |
Validity period for the token, if not given set to max validity allowed for the token scope. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/tokens' -i -X POST \
-d 'validity=PT1H'
Example Response
POST /v2/accounts/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 13
validity=PT1H
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 146
{
"type" : "LimitExceededException",
"code" : 400,
"message" : "Validity period exceeds maximum allowed for token of scope AUTHENTICATION"
}
Remove Token
DELETE /v2/accounts/tokens
Removes a token from an account where both the account and the token to process are retrieved from the security context.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/tokens' -i -X DELETE
Example Response
DELETE /v2/accounts/tokens HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Unauthorized security issuer"
}
Verify Password
POST /v2/accounts/{identifier}/password/verify
Verifies the active password for a PID account.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].
Path Parameters
Parameter | Description |
---|---|
|
Identifier of the account. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Active password for the account. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/accounts/verify-pass-pos/password/verify' -i -X POST \
-d 'pass=Th3P%40ssword%21'
Example Response
POST /v2/accounts/verify-pass-pos/password/verify HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 21
pass=Th3P%40ssword%21
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Account with ID username not found"
}
Banner Replication API
Person Completely Updated
POST /v1/replication/banner/consume
Processes a Banner PERSONSET
XML message.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/replication-banner ].
Example Request
$ curl 'https://api.middleware.vt.edu/v1/replication/banner/consume' -i -X POST \
-H 'Content-Type: text/xml;charset=UTF-8' \
-d '<?xml version="1.0"?>
<PERSONSET>
<PERSON>
<BANNER_PIDM>7851451</BANNER_PIDM>
<VT_IDNUM>916582945</VT_IDNUM>
<UDC_IDENTIFIER>wynjITOTjVDLgDlMkkNoc6sZpkiRK1On</UDC_IDENTIFIER>
<SSN_HASH>5j2s1isTALxcpVBXd6hJNUJyOMaYBByXNMR7DOB0irI=</SSN_HASH>
<NAMESET>
<BANNERNAME>
<LASTNAME></LASTNAME>
<FIRSTNAME></FIRSTNAME>
<MIDDLENAME>IS</MIDDLENAME>
<SUFFIX></SUFFIX>
</BANNERNAME>
</NAMESET>
<BIRTHDATE>1990-11-30</BIRTHDATE>
<CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
<DECEASED_FLAG>0</DECEASED_FLAG>
<GENDER>M</GENDER>
<AFFILIATION_DATA>
<AFFILIATION>VT-ALUM</AFFILIATION>
<AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
<AFFILIATION>VT-EMPLOYEE</AFFILIATION>
<AFFILIATION>VT-EMPLOYEE-STATE</AFFILIATION>
<AFFILIATION>VT-FACULTY</AFFILIATION>
<AFFILIATION>VT-STUDENT</AFFILIATION>
</AFFILIATION_DATA>
<ADDRESS_SET>
<ADDRESS TYPE="MA">
<STREET1>1500 Maple St</STREET1>
<STREET2>Tree #2</STREET2>
<STREET3>Limb #1</STREET3>
<CITY>War</CITY>
<STATE_CODE>WV</STATE_CODE>
<POSTALCODE>24892</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
<MAILSTOP></MAILSTOP>
<PHONESET>
<PHONE TYPE="MA">
<NUMBER>5405551212</NUMBER>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
<ADDRESS TYPE="OF">
<STREET1>SETI-Middleware</STREET1>
<STREET2>1700 Pratt Drive</STREET2>
<STREET3></STREET3>
<CITY>Blacksburg</CITY>
<STATE_CODE>VA</STATE_CODE>
<POSTALCODE>24060</POSTALCODE>
<COUNTRY></COUNTRY>
<UNLISTED_FLAG>0</UNLISTED_FLAG>
<MAILSTOP>0479</MAILSTOP>
<PHONESET>
<PHONE TYPE="OF">
<NUMBER>5402314357</NUMBER>
<UNLISTED_FLAG>0</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
</ADDRESS_SET>
<EMPLOYEE_DATA>
<EMPLOYEE_TYPE>3A</EMPLOYEE_TYPE>
<JOB_TITLE>Trouble Maker</JOB_TITLE>
<EMPLOYEE_STATUS>A</EMPLOYEE_STATUS>
<HIREDATE>2010-01-01</HIREDATE>
<TERMDATE></TERMDATE>
<DEPT>066103</DEPT>
<CONFIDENTIAL>1</CONFIDENTIAL>
<OFFCAMPUS>0</OFFCAMPUS>
</EMPLOYEE_DATA>
<STUDENT_DATA>
<CAMPUS>0</CAMPUS>
<ACADEMIC_LEVEL>41</ACADEMIC_LEVEL>
<GEN_ACADEMIC_LEVEL>UG</GEN_ACADEMIC_LEVEL>
<STATUS></STATUS>
<LASTTERM>200701</LASTTERM>
<NEXTTERM></NEXTTERM>
<COLLEGE>08</COLLEGE>
<MAJOR>BIOL</MAJOR>
<DEGREE_SET>
<DEGREE>
<LEVEL>UG</LEVEL>
<CODE>BS</CODE>
<MAJOR>BIOL</MAJOR>
</DEGREE>
<DEGREE>
<LEVEL>UG</LEVEL>
<CODE>BA</CODE>
<MAJOR>MATH</MAJOR>
</DEGREE>
</DEGREE_SET>
<MAJOR_SET>
<MAJOR>BIOL</MAJOR>
</MAJOR_SET>
</STUDENT_DATA>
<NONVT_DATA>
<EMAIL TYPE="ME">
<EMAIL_ADDRESS>hizzy@vcom.edu</EMAIL_ADDRESS>
</EMAIL>
</NONVT_DATA>
</PERSON>
</PERSONSET>
'
Example Response
POST /v1/replication/banner/consume HTTP/1.1
Content-Type: text/xml;charset=UTF-8
Content-Length: 3137
Host: api.middleware.vt.edu
<?xml version="1.0"?>
<PERSONSET>
<PERSON>
<BANNER_PIDM>7851451</BANNER_PIDM>
<VT_IDNUM>916582945</VT_IDNUM>
<UDC_IDENTIFIER>wynjITOTjVDLgDlMkkNoc6sZpkiRK1On</UDC_IDENTIFIER>
<SSN_HASH>5j2s1isTALxcpVBXd6hJNUJyOMaYBByXNMR7DOB0irI=</SSN_HASH>
<NAMESET>
<BANNERNAME>
<LASTNAME></LASTNAME>
<FIRSTNAME></FIRSTNAME>
<MIDDLENAME>IS</MIDDLENAME>
<SUFFIX></SUFFIX>
</BANNERNAME>
</NAMESET>
<BIRTHDATE>1990-11-30</BIRTHDATE>
<CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
<DECEASED_FLAG>0</DECEASED_FLAG>
<GENDER>M</GENDER>
<AFFILIATION_DATA>
<AFFILIATION>VT-ALUM</AFFILIATION>
<AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
<AFFILIATION>VT-EMPLOYEE</AFFILIATION>
<AFFILIATION>VT-EMPLOYEE-STATE</AFFILIATION>
<AFFILIATION>VT-FACULTY</AFFILIATION>
<AFFILIATION>VT-STUDENT</AFFILIATION>
</AFFILIATION_DATA>
<ADDRESS_SET>
<ADDRESS TYPE="MA">
<STREET1>1500 Maple St</STREET1>
<STREET2>Tree #2</STREET2>
<STREET3>Limb #1</STREET3>
<CITY>War</CITY>
<STATE_CODE>WV</STATE_CODE>
<POSTALCODE>24892</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
<MAILSTOP></MAILSTOP>
<PHONESET>
<PHONE TYPE="MA">
<NUMBER>5405551212</NUMBER>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
<ADDRESS TYPE="OF">
<STREET1>SETI-Middleware</STREET1>
<STREET2>1700 Pratt Drive</STREET2>
<STREET3></STREET3>
<CITY>Blacksburg</CITY>
<STATE_CODE>VA</STATE_CODE>
<POSTALCODE>24060</POSTALCODE>
<COUNTRY></COUNTRY>
<UNLISTED_FLAG>0</UNLISTED_FLAG>
<MAILSTOP>0479</MAILSTOP>
<PHONESET>
<PHONE TYPE="OF">
<NUMBER>5402314357</NUMBER>
<UNLISTED_FLAG>0</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
</ADDRESS_SET>
<EMPLOYEE_DATA>
<EMPLOYEE_TYPE>3A</EMPLOYEE_TYPE>
<JOB_TITLE>Trouble Maker</JOB_TITLE>
<EMPLOYEE_STATUS>A</EMPLOYEE_STATUS>
<HIREDATE>2010-01-01</HIREDATE>
<TERMDATE></TERMDATE>
<DEPT>066103</DEPT>
<CONFIDENTIAL>1</CONFIDENTIAL>
<OFFCAMPUS>0</OFFCAMPUS>
</EMPLOYEE_DATA>
<STUDENT_DATA>
<CAMPUS>0</CAMPUS>
<ACADEMIC_LEVEL>41</ACADEMIC_LEVEL>
<GEN_ACADEMIC_LEVEL>UG</GEN_ACADEMIC_LEVEL>
<STATUS></STATUS>
<LASTTERM>200701</LASTTERM>
<NEXTTERM></NEXTTERM>
<COLLEGE>08</COLLEGE>
<MAJOR>BIOL</MAJOR>
<DEGREE_SET>
<DEGREE>
<LEVEL>UG</LEVEL>
<CODE>BS</CODE>
<MAJOR>BIOL</MAJOR>
</DEGREE>
<DEGREE>
<LEVEL>UG</LEVEL>
<CODE>BA</CODE>
<MAJOR>MATH</MAJOR>
</DEGREE>
</DEGREE_SET>
<MAJOR_SET>
<MAJOR>BIOL</MAJOR>
</MAJOR_SET>
</STUDENT_DATA>
<NONVT_DATA>
<EMAIL TYPE="ME">
<EMAIL_ADDRESS>hizzy@vcom.edu</EMAIL_ADDRESS>
</EMAIL>
</NONVT_DATA>
</PERSON>
</PERSONSET>
Example Error Response
HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 141
{
"type" : "InsufficientAuthenticationException",
"code" : 401,
"message" : "Full authentication is required to access this resource"
}
Person Partially Updated
POST /v1/replication/banner/consume
Processes a Banner PERSONSET
XML message.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/replication-banner ].
Example Request
$ curl 'https://api.middleware.vt.edu/v1/replication/banner/consume' -i -X POST \
-H 'Content-Type: text/xml;charset=UTF-8' \
-d '<?xml version="1.0"?>
<!--
~ See LICENSE for licensing and NOTICE for copyright.
-->
<PERSONSET>
<PERSON>
<BANNER_PIDM>8675309</BANNER_PIDM>
<VT_IDNUM>123</VT_IDNUM>
<UDC_IDENTIFIER>abcde</UDC_IDENTIFIER>
<NAMESET>
<BANNERNAME>
<LASTNAME>Bibblebush</LASTNAME>
<FIRSTNAME>Bertha</FIRSTNAME>
<MIDDLENAME>B</MIDDLENAME>
<SUFFIX></SUFFIX>
</BANNERNAME>
</NAMESET>
<BIRTHDATE>1990-11-30</BIRTHDATE>
<CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
<DECEASED_FLAG>0</DECEASED_FLAG>
<GENDER>F</GENDER>
<AFFILIATION_DATA>
<AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
</AFFILIATION_DATA>
<ADDRESS_SET>
<ADDRESS TYPE="MA">
<STREET1>133 Worthington Way</STREET1>
<STREET2>Apt 1A</STREET2>
<!-- Next field exceeds constraint of 100 characters. -->
<STREET3>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</STREET3>
<CITY>Cambridge</CITY>
<STATE_CODE>MA</STATE_CODE>
<POSTALCODE>02138</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
<MAILSTOP></MAILSTOP>
<PHONESET>
<PHONE TYPE="MA">
<NUMBER>A12345678</NUMBER>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
</ADDRESS_SET>
</PERSON>
</PERSONSET>
'
Example Response
POST /v1/replication/banner/consume HTTP/1.1
Content-Type: text/xml;charset=UTF-8
Content-Length: 1429
Host: api.middleware.vt.edu
<?xml version="1.0"?>
<!--
~ See LICENSE for licensing and NOTICE for copyright.
-->
<PERSONSET>
<PERSON>
<BANNER_PIDM>8675309</BANNER_PIDM>
<VT_IDNUM>123</VT_IDNUM>
<UDC_IDENTIFIER>abcde</UDC_IDENTIFIER>
<NAMESET>
<BANNERNAME>
<LASTNAME>Bibblebush</LASTNAME>
<FIRSTNAME>Bertha</FIRSTNAME>
<MIDDLENAME>B</MIDDLENAME>
<SUFFIX></SUFFIX>
</BANNERNAME>
</NAMESET>
<BIRTHDATE>1990-11-30</BIRTHDATE>
<CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
<DECEASED_FLAG>0</DECEASED_FLAG>
<GENDER>F</GENDER>
<AFFILIATION_DATA>
<AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
</AFFILIATION_DATA>
<ADDRESS_SET>
<ADDRESS TYPE="MA">
<STREET1>133 Worthington Way</STREET1>
<STREET2>Apt 1A</STREET2>
<!-- Next field exceeds constraint of 100 characters. -->
<STREET3>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</STREET3>
<CITY>Cambridge</CITY>
<STATE_CODE>MA</STATE_CODE>
<POSTALCODE>02138</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
<MAILSTOP></MAILSTOP>
<PHONESET>
<PHONE TYPE="MA">
<NUMBER>A12345678</NUMBER>
<UNLISTED_FLAG>1</UNLISTED_FLAG>
</PHONE>
</PHONESET>
</ADDRESS>
</ADDRESS_SET>
</PERSON>
</PERSONSET>
Dev Team Resource API
Fetch
GET /v1/devteams/{name}
Fetches the developer team with the given name.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].
Path Parameters
Parameter | Description |
---|---|
|
Name of developer team to fetch. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/devteams/the-a-team' -i -X GET
Example Response
GET /v1/devteams/the-a-team HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 110
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Group with ID developer.someteam not found"
}
Query
GET /v1/devteams
Query for developer teams that the current principal is authorized to view.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Optional name expression to limit results to developer teams matching the given name. Supports wildcards, e.g. dbaa*. |
|
|
Optional member uid used to select teams containing the given member. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/devteams?name=the-*&member=20011610' -i -X GET
Example Response
GET /v1/devteams?name=the-*&member=20011610 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Create
POST /v1/devteams
Creates a new developer team.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Developer team name. |
|
false |
One or more names of groups to nest inside the developer team group. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/devteams' -i -X POST \
-d 'name=the-b-team&member=member1&member=member2'
Example Response
POST /v1/devteams HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 45
name=the-b-team&member=member1&member=member2
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Entitlement Resource API
Fetch
GET /v1/entitlements/{id}
Fetches the entitlement with the given unique identifier.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
ID of entitlement. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements/1977?with=viewers' -i -X GET
Example Response
GET /v1/entitlements/1977?with=viewers HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Grant with ID 19591000 not found"
}
Query
GET /v1/entitlements
Fetches a collection of entitlement resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
User bearing the entitlement |
|
|
Service bearing the entitlement |
|
|
Group bearing the entitlement |
|
|
Principal who is the owner(manager) of the entitlement |
|
|
Name of the entitlement |
|
|
Sponsor of the entitlement |
|
|
Subject in viewer role on the entitlement |
|
|
Zero or more optional sections of fields to include in fetched resources. |
|
|
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
|
|
Size of the page you want to retrieve. Must be greater than 0. |
|
|
How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements?name=ed%2Ftest%2Fent%2F*&owner=middleware-test' -i -X GET
Example Response
GET /v1/entitlements?name=ed%2Ftest%2Fent%2F*&owner=middleware-test HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Create
POST /v2/entitlements
Creates an entitlement.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Resource of the entitlement. |
|
true |
Scope of the entitlement. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/entitlements' -i -X POST \
-d 'resource=test%2Fresource'
Example Response
POST /v2/entitlements HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 24
resource=test%2Fresource
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 129
{
"type" : "FoundException",
"code" : 409,
"message" : "Entitlement with ID middleware-test:test/resource already exists"
}
Delete
DELETE /v2/entitlements/{id}
Deletes the given entitlement.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
A unique identifier for the entitlement. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/entitlements/20015164' -i -X DELETE
Example Response
DELETE /v2/entitlements/20015164 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 101
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Entitlement with ID 123 not found"
}
Create And Grant
POST /v1/entitlements
Creates an entitlement and grants it to a subject identified by either the user
or service
parameters (one or the other is required).
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Entitlement resource URI. |
|
true |
Scope of the entitlement. |
|
true |
User to whom to grant the entitlement. |
|
true |
Service to which to grant the entitlement. |
|
true |
User who initiated the granting of the entitlement. If not specified, the principal that invokes the operation is the grantor. |
|
true |
Expiration date after which the granted entitlement is automatically revoked by the system. |
|
true |
Zero or more service viewers of the entitlement. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements' -i -X POST \
-d 'name=test%2Fent%2F5&person=800001&expiration=1893456000'
Example Response
POST /v1/entitlements HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 55
name=test%2Fent%2F5&person=800001&expiration=1893456000
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 94
{
"type" : "NotFoundException",
"code" : 404,
"message" : "User with ID 123 not found"
}
Revoke
DELETE /v1/entitlements/{id}
Revokes the given grant (equivalent of EDv4 entitlement).
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
ID of grant. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements/2041' -i -X DELETE
Example Response
DELETE /v1/entitlements/2041 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 97
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Grant with ID 12345 not found"
}
Add Viewers
POST /v1/entitlements/{uid}/viewers
Adds the given service viewers to an existing entitlement.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
ID of grant. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
true |
Expiration date of viewer role. |
|
false |
Username of services to add as viewers of the entitlement. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements/1962/viewers' -i -X POST \
-d 'viewer=svc-v1&viewer=svc-v2'
Example Response
POST /v1/entitlements/1962/viewers HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 27
viewer=svc-v1&viewer=svc-v2
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104
{
"type" : "FoundException",
"code" : 409,
"message" : "Subject with ID 20015232 already exists"
}
Remove Viewer
DELETE /v1/entitlements/{uid}/viewers/{id}
Removes the given service viewer from an existing entitlement.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
ID of grant. |
|
Username of service viewer to remove. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements/2028/viewers/svc-v2' -i -X DELETE
Example Response
DELETE /v1/entitlements/2028/viewers/svc-v2 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Subject with ID 20014974 not found"
}
Update Relation
PATCH /v1/entitlements/{uid}/{role}/{id}
Updates the entitlement relation given a JSON patch.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].
Path Parameters
Parameter | Description |
---|---|
|
ID of grant. |
|
Entitlement role. At present, only viewers are supported. |
|
Username of service to update. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/entitlements/1957/viewers/svc-v1' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/expiration","value":31536000}]'
Example Response
PATCH /v1/entitlements/1957/viewers/svc-v1 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 56
Host: api.middleware.vt.edu
[{"op":"replace","path":"/expiration","value":31536000}]
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Service with ID svc-v1 not found"
}
Group Resource API
Fetch
GET /v1/groups/{uugid}
Fetches the group with the given unique name.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Name of group to fetch. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched group resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/middleware.dvlp?with=members&with=membership&with=replication&with=suppression' -i -X GET
Example Response
GET /v1/groups/middleware.dvlp?with=members&with=membership&with=replication&with=suppression HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 107
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Group with ID middleware.dvlp not found"
}
Fetch Relation
GET /v1/groups/{uugid}/{role}/{id}
Fetches a relation on a group for a specific subject.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Name of group to search. |
|
Role the subject belongs to on the group. Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ] |
|
Unique identifier of the subject to fetch. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
The kind of subject. Must be one of: [ GROUP, PERSON, SERVICE ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/group.a/members/middleware' -i -X GET
Example Response
GET /v1/groups/group.a/members/middleware HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 168
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'unknown'. Valid types: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]"
}
Query
GET /v1/groups?uugid=middleware*
Fetches a collection of group resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Unique identifier |
|
|
Created date after |
|
|
Created date before |
|
|
Expiration date after |
|
|
Expiration date before |
|
|
Group member name (may be an account username identifying a person or service or group name) |
|
|
Nested group name (use this parameter if you are seaching for child groups explicitly) |
|
|
Subject in administrator role |
|
|
Subject in contact role (deprecated) |
|
|
Subject in manager role |
|
|
Subject in viewer role |
|
|
Zero or more optional sections of fields to include in fetched group resources. |
|
|
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
|
|
Size of the page you want to retrieve. Must be greater than 0. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups?uugid=middleware*' -i -X GET
Example Response
GET /v1/groups?uugid=middleware* HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Create
POST /v1/groups
Creates a new group resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Unique group name of group to create. |
|
false |
One or more group contacts. |
|
false |
One or more group administrators. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups' -i -X POST \
-d 'uugid=test.group-1&administrator=alice&administrator=bob&contact=bob'
Example Response
POST /v1/groups HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68
uugid=test.group-1&administrator=alice&administrator=bob&contact=bob
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 143
{
"type" : "PolicyException",
"code" : 400,
"message" : "middleware-test must be an administrator of a parent group to create test.aaa"
}
Add Relation
POST /v1/groups/{uugid}/{role}
Adds a member to a group role/relation.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
ID of group to update. |
|
Role to add members to. Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ] |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Kind of member to add. Must be one of: [ GROUP, PERSON, SERVICE ] |
|
false |
Username or UID of subject to add. Only username is allowed for Admin and Contact. |
|
true |
Expiration date. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.group/administrators' -i -X POST \
-d 'id=connie&kind=person'
Example Response
POST /v1/groups/test.group/administrators HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 21
id=connie&kind=person
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 143
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'invalid-kind'. Valid types: [ GROUP, PERSON, SERVICE ]"
}
Remove Relation
DELETE /v1/groups/{uugid}/{role}/{id}
Removes a member from a group role/relation.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
ID of group to update. |
|
Role to remove members from. Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ] |
|
Username or UID of subject to remove from role. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Kind of member to remove. Must be one of: [ GROUP, PERSON, SERVICE ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.group/members/pidlike?kind=person' -i -X DELETE \
-H 'Content-Type: application/x-www-form-urlencoded'
Example Response
DELETE /v1/groups/test.group/members/pidlike?kind=person HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/groups/test.update/contacts/alice
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Update Relation
PATCH /v1/groups/{uugid}/{role}/{id}
Updates the group relation given a JSON patch.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Group unique name. |
|
Group role. Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ] |
|
Id of group relation subject to update. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Kind of subject. Must be one of: [ GROUP, PERSON, SERVICE ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.update/managers/middleware-test?kind=service' -i -X PATCH \
-H 'Content-Type: application/json-patch+json;charset=utf-8' \
-d '[{"op":"replace","path":"/expirationDate","value":1762033198}]'
Example Response
PATCH /v1/groups/test.update/managers/middleware-test?kind=service HTTP/1.1
Content-Type: application/json-patch+json;charset=utf-8
Content-Length: 62
Host: api.middleware.vt.edu
[{"op":"replace","path":"/expirationDate","value":1762033198}]
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 291
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Failed applying patch: Group does not support expiration in ADMIN role\n at [Source: UNKNOWN; byte offset: #UNKNOWN] (through reference chain: edu.vt.middleware.ed.ws.rest.model.JsonGroupRelative[\"expirationDate\"])"
}
Update
PATCH /v1/groups/{uugid}
Updates the group given a JSON patch.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Group unique name. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.group.arsenic' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/suppressDisplay","value":true},{"op":"replace","path":"/expirationDate","value":1762033171},{"op":"replace","path":"/displayName","value":"a common n-type dopant in semiconductor electronic devices"}]'
Example Response
PATCH /v1/groups/test.group.arsenic HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 226
Host: api.middleware.vt.edu
[{"op":"replace","path":"/suppressDisplay","value":true},{"op":"replace","path":"/expirationDate","value":1762033171},{"op":"replace","path":"/displayName","value":"a common n-type dopant in semiconductor electronic devices"}]
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 134
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Failed applying patch: no such path in target JSON document"
}
Delete
DELETE /v1/groups/{uugid}
Deletes a group resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
ID of group to delete. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.middle.leaf' -i -X DELETE
Example Response
DELETE /v1/groups/test.middle.leaf HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Group with ID does-not-exist not found"
}
Batch Add Relations
POST /v1/groups/{uugid}/relations
Batch adds the given relations.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Group to modify. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.batch.two/relations' -i -X POST \
-H 'Content-Type: application/json' \
-d '[{"role":"members","kind":"person","id":"alpha"},{"role":"members","kind":"person","id":"beta"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"service","id":"delta"},{"role":"members","kind":"service","id":"notfound1"},{"role":"members","kind":"service","id":"notfound2"},{"role":"administrators","kind":"person","id":"alpha"},{"role":"administrators","kind":"service","id":"delta"},{"role":"administrators","kind":"service","id":"notfound2"},{"role":"viewers","kind":"service","id":"epsilon"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]'
Example Response
POST /v1/groups/test.batch.two/relations HTTP/1.1
Content-Type: application/json
Content-Length: 671
Host: api.middleware.vt.edu
[{"role":"members","kind":"person","id":"alpha"},{"role":"members","kind":"person","id":"beta"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"service","id":"delta"},{"role":"members","kind":"service","id":"notfound1"},{"role":"members","kind":"service","id":"notfound2"},{"role":"administrators","kind":"person","id":"alpha"},{"role":"administrators","kind":"service","id":"delta"},{"role":"administrators","kind":"service","id":"notfound2"},{"role":"viewers","kind":"service","id":"epsilon"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]
Batch Remove Relations
DELETE /v1/groups/{uugid}/relations
Batch removes the given relations.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].
Path Parameters
Parameter | Description |
---|---|
|
Group to modify. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/groups/test.batch.three/relations' -i -X DELETE \
-H 'Content-Type: application/json' \
-d '[{"role":"members","kind":"person","id":"anna"},{"role":"members","kind":"person","id":"beth"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"service","id":"dave"},{"role":"administrators","kind":"person","id":"anna"},{"role":"administrators","kind":"service","id":"dave"},{"role":"viewers","kind":"service","id":"ernie"},{"role":"viewers","kind":"service","id":"notfound1"},{"role":"viewers","kind":"service","id":"notfound2"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]'
Example Response
DELETE /v1/groups/test.batch.three/relations HTTP/1.1
Content-Type: application/json
Content-Length: 605
Host: api.middleware.vt.edu
[{"role":"members","kind":"person","id":"anna"},{"role":"members","kind":"person","id":"beth"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"service","id":"dave"},{"role":"administrators","kind":"person","id":"anna"},{"role":"administrators","kind":"service","id":"dave"},{"role":"viewers","kind":"service","id":"ernie"},{"role":"viewers","kind":"service","id":"notfound1"},{"role":"viewers","kind":"service","id":"notfound2"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]
ID Proof Resource API
Grade
POST /v1/persons/{uid}/questions/{qid}/grade
Grades a single answer as a pass/fail.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons-challenge ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user whose challenge question is being graded. |
|
Question id of the question being graded. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
To be graded. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/persons/20013907/questions/fname/grade' -i -X POST \
-d 'answer=Alice'
Example Response
POST /v1/persons/20013907/questions/fname/grade HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 12
answer=Alice
Example Error Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 20
{
"pass" : false
}
Questions
GET /v1/persons/{uid}/questions
Returns a list of questions based on affiliations. The ordered/prioritized Map of question types is iterated and the first matching affiliation of the person is used to populate the questions.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons-challenge ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user whose identity challenge questions will be returned. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/persons/20013923/questions' -i -X GET
Example Response
GET /v1/persons/20013923/questions HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Mailbox Resource API
Fetch
GET /v2/mailboxes/{address}
Fetches the mailbox with the given unique address identifier - an Email
.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Address of mailbox to fetch. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched mailbox resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu?with=addresses&with=state' -i -X GET
Example Response
GET /v2/mailboxes/alice@vt.edu?with=addresses&with=state HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Mailbox with ID alice@vt.edu not found"
}
Query
GET /v2/mailboxes?any=match*&type=forwarding&with=state
Fetches a collection of mailbox resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Primary (MAILBOX) address of the mailbox |
|
|
ALIAS address of the mailbox |
|
|
FORWARD address of the mailbox |
|
|
Any type of address of the mailbox (MAILBOX, ALIAS, FORWARD) |
|
|
Username of the mailbox owner |
|
|
Type of the mailbox |
|
|
State of the mailbox |
|
|
UID of the mailbox owner |
|
|
Mailbox expiring after the given date |
|
|
Mailbox expiring before the given date |
|
|
Zero or more optional sections of fields to include in fetched mailbox resources. |
|
|
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
|
|
Size of the page you want to retrieve. Must be greater than 0. |
|
|
How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes?any=match*&type=forwarding&with=state' -i -X GET
Example Response
GET /v2/mailboxes?any=match*&type=forwarding&with=state HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Alias
POST /v2/mailboxes/{address}/aliases
Adds an email alias to a mailbox resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Email address to add as an alias of the mailbox. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/aliases' -i -X POST \
-d 'alias=alias%40vt.edu'
Example Response
POST /v2/mailboxes/alice@vt.edu/aliases HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 20
alias=alias%40vt.edu
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "FoundException",
"code" : 409,
"message" : "Email with ID alias@vt.edu already exists"
}
Remove Alias
DELETE /v2/mailboxes/{address}/aliases/{alias}
Removes an email alias from a mailbox resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
|
Email address to remove from the aliases of the mailbox. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/aliases/alias@vt.edu' -i -X DELETE
Example Response
DELETE /v2/mailboxes/alice@vt.edu/aliases/alias@vt.edu HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Email with ID alias@vt.edu not found"
}
Add Forward
POST /v2/mailboxes/{address}/forwards
Adds a forward to a mailbox resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Email address to add as a forward to mailbox. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/forwards' -i -X POST \
-d 'forward=forward%40vt.edu'
Example Response
POST /v2/mailboxes/alice@vt.edu/forwards HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 24
forward=forward%40vt.edu
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108
{
"type" : "FoundException",
"code" : 409,
"message" : "Email with ID forward@vt.edu already exists"
}
Remove Forward
DELETE /v2/mailboxes/{address}/forwards/{forward}
Removes a forward from a mailbox resource.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
|
Email address to remove from the forwards of the mailbox. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/forwards/forward@vt.edu' -i -X DELETE
Example Response
DELETE /v2/mailboxes/alice@vt.edu/forwards/forward@vt.edu HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Email with ID forward@vt.edu not found"
}
Update Mail Preferred Address
PATCH /v2/mailboxes/{address}
Updates an existing mailbox.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/primary@vt.edu' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/preferredAddress","value":"preferred-alias@vt.edu"}]'
Example Response
PATCH /v2/mailboxes/primary@vt.edu HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 78
Host: api.middleware.vt.edu
[{"op":"replace","path":"/preferredAddress","value":"preferred-alias@vt.edu"}]
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Update Mail Route
PATCH /v2/mailboxes/{address}
Updates an existing mailbox route.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].
Path Parameters
Parameter | Description |
---|---|
|
Unique string identifier of the mailbox to update, which is its primary address. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/routeType","value":"exchange"}]'
Example Response
PATCH /v2/mailboxes/alice@vt.edu HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 57
Host: api.middleware.vt.edu
[{"op":"replace","path":"/routeType","value":"exchange"}]
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Mailbox with ID alice@vt.edu not found"
}
Namespace Resource API
Is Available
GET /v2/namespaces/{namespace}/values/{value}
Checks if the given namespace:value combination is available.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].
Path Parameters
Parameter | Description |
---|---|
|
The namespace to check. Must be one of: [ COALITION, EMAIL, GROUP, OAUTH2, PAIRWISE, PIDM, RESERVED, SAML, SSN, SUBJECT, UDCID, USERNAME, VTID ] |
|
The namespace value. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/namespaces/username/values/iap.username' -i -X GET
Example Response
GET /v2/namespaces/username/values/iap.username HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 21
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
{
"value" : false
}
Reserve
POST /v2/namespaces/reserved
Reserves the given name in the Enterprise Directory such that it is subsequently ineligible for allocation in any namespace in the Enterprise Directory.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Namespace value to reserve. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/namespaces/reserved' -i -X POST \
-d 'value=rp.username'
Example Response
POST /v2/namespaces/reserved HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 17
value=rp.username
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108
{
"type" : "FoundException",
"code" : 409,
"message" : "Reserve with ID rnf.username already exists"
}
Unreserve
DELETE /v2/namespaces/reserved/{value}
Removes the given reserved name in the Enterprise Directory such that it is subsequently eligible for allocation.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].
Path Parameters
Parameter | Description |
---|---|
|
Namespace value for which to remove reservation. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/namespaces/reserved/urp.username' -i -X DELETE
Example Response
DELETE /v2/namespaces/reserved/urp.username HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Reserve with ID urnnf.username not found"
}
Password Complexity API
Validate
POST /v1/password/validate
Validates a password.
Authorization
HTTP Auth is not required.
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Userid associated with the password. |
|
false |
To check complexity. |
|
true |
Of the userid. Must be one of: [ AD, BANNER, ORACLE, PID ] |
|
true |
To include in the response. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/password/validate' -i -X POST \
-d 'userid=dfisher&password=testingpasss&with=messages&with=details'
Example Response
POST /v1/password/validate HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 63
userid=dfisher&password=testingpasss&with=messages&with=details
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 103
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Illegal sections: [badinput]"
}
Rules
GET /v1/password/rules?type=pid
Returns the password validation rules.
Authorization
HTTP Auth is not required.
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Of the desired rule set. Must be one of: [ AD, BANNER, ORACLE, PID ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/password/rules?type=pid' -i -X GET
Example Response
GET /v1/password/rules?type=pid HTTP/1.1
Host: api.middleware.vt.edu
Person LDAP Search API
Fuzzy
GET /v1/persons/ldap/fuzzysearch?query=stone&attr=givenName
Performs a fuzzy LDAP search.
Authorization
HTTP Auth is not required.
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
To search against the template. |
|
|
Attributes to return. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/persons/ldap/fuzzysearch?query=stone&attr=givenName' -i -X GET
Example Response
GET /v1/persons/ldap/fuzzysearch?query=stone&attr=givenName HTTP/1.1
Host: api.middleware.vt.edu
Search
GET /v1/persons/ldap/search?filter=(givenName=b*)&attr=sn
Performs an LDAP search.
Authorization
HTTP Auth is not required.
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
To execute against the ldap. |
|
|
Attributes to return. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/persons/ldap/search?filter=(givenName%3Db*)&attr=sn' -i -X GET
Example Response
GET /v1/persons/ldap/search?filter=(givenName%3Db*)&attr=sn HTTP/1.1
Host: api.middleware.vt.edu
Person Resource API
Delete
DELETE /v2/persons/{uid}
Deletes the Person.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons ].
Path Parameters
Parameter | Description |
---|---|
|
UID of person. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/persons/20014845' -i -X DELETE
Example Response
DELETE /v2/persons/20014845 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 164
{
"type" : "BlockingDataException",
"code" : 400,
"message" : "The delete on Donald Duck was blocked by existence of [User(ID=20014854), User(ID=20014856)]"
}
Service Resource API
Create
POST /v1/services
Creates a new service using an authenticated Service
principal that is authorized to create services. Services are permitted to invoke this endpoint by granting the following middleware entitlements: - ed/rest/services
- ed/manage/service-manager#create-service
.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Service unique identifier; follows requirements for ED account usernames. |
|
false |
Requested service expiration date expressed as a Unix epoch (int) or date string in ISO 8601 format. |
|
false |
List of one or more service administrators identified by username (or group name if a group). |
|
true |
List of zero or more service contacts identified by username (or group name if a group). |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services' -i -X POST \
-d 'uusid=waw&expires=1762033060&administrator=andy&contact=candace'
Example Response
POST /v1/services HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 63
uusid=waw&expires=1762033060&administrator=andy&contact=candace
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Account with ID nobody not found"
}
Fetch
GET /v1/services/{uusid}
Fetches a service resource that is uniquely identified by the given uusid.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
Service unique string identifier. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched service resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/iota?with=all' -i -X GET
Example Response
GET /v1/services/iota?with=all HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Query
GET /v1/services
Fetches a collection of service resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
OAuth2 client identifier |
|
|
Created date after |
|
|
Created date before |
|
|
Developer team name |
|
|
SAML entity ID |
|
|
Attribute service can access |
|
|
Unique identifier |
|
|
Subject in administrator role |
|
|
Subject in contact role (deprecated) |
|
|
Subject in manager role |
|
|
Zero or more optional sections of fields to include in fetched service resources. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services?client_id=a97fb5b1-ae12-1008-9c62-000edf235d76' -i -X GET
Example Response
GET /v1/services?client_id=a97fb5b1-ae12-1008-9c62-000edf235d76 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Relation
POST /v1/services/{uusid}/{role}
Adds a member to a service role/relation.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
|
Role to add members to. Must be one of: [ ADMINISTRATORS, CONTACTS, VIEWERS ] |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Kind of member to add. Must be one of: [ GROUP, PERSON, SERVICE ] |
|
false |
Unique identifier of member to add. |
|
true |
Requested service expiration date expressed as a Unix epoch (int) or date string in ISO 8601 format. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/alpha/administrators' -i -X POST \
-d 'id=alice&kind=person&expiration=2024-12-01T17%3A37%3A57.169750228-05%3A00'
Example Response
POST /v1/services/alpha/administrators HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 73
id=alice&kind=person&expiration=2024-12-01T17%3A37%3A57.169750228-05%3A00
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Remove Relation
DELETE /v1/services/{uusid}/{role}/{id}
Removes a member from a service role/relation.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
|
Role to remove member from. Must be one of: [ ADMINISTRATORS, CONTACTS, VIEWERS ] |
|
ID of member to remove from role. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/alpha/administrators/test.middleware-group' -i -X DELETE
Example Response
DELETE /v1/services/alpha/administrators/test.middleware-group HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Shelve
POST /v2/services/{uusid}/shelve
Shelves a service account. Sets the primary account state to SHELVED.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
Service account to shelve. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/services/middleware-shelve/shelve' -i -X POST
Example Response
POST /v2/services/middleware-shelve/shelve HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Viewable Person Attributes
POST /v1/services/{uusid}/viewable-person-attributes
Adds one or more viewable person attributes to a service.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
List of person attributes, one for each occurrence of attribute in the entity body. Must be one of: [ academicLevel, accountCheckupDate, accountCreationDate, accountExpirationDate, accountShelveDate, accountSponsor, accountState, accountTransition, authId, bannerName, bannerPIDM, c, campus, channel, city, classLevel, classLevelCode, cn, coalitionID, college, creationDate, dateOfBirth, deceasedFlag, degreeType, department, departmentNumber, displayName, eduPersonAffiliation, eduPersonAssurance, eduPersonEntitlement, eduPersonNickname, eduPersonOrcid, eduPersonOrgDN, eduPersonOrgUnitDN, eduPersonPrimaryAffiliation, eduPersonPrimaryOrgUnitDN, eduPersonPrincipalName, eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonUniqueId, employeeConfidential, employeeOffCampus, facsimileTelephoneNumber, gender, gidNumber, givenName, googleMailbox, groupMembership, groupMembershipUugid, guestId, hokiesPassword, homeDirectory, homeFax, homeMobile, homePager, homePhone, homePostalAddress, instantMessagingID, isMemberOf, l, labeledURI, lastEnrollmentTerm, lastEnrollmentTermCode, localFax, localMobile, localPager, localPhone, localPostalAddress, mail, mailAccount, mailAccountState, mailAlias, mailAuxiliaryAccount, mailDisplayAddress, mailExternalAddress, mailForwardingAddress, mailPreferredAddress, mailStop, major, majorCode, middleName, mobile, modificationDate, networkPassword, nextEnrollmentTerm, nextEnrollmentTermCode, objectClass, ou, pager, pairwiseId, passwordChangeDate, passwordExpirationDate, passwordState, personType, postOfficeBox, postalAddress, postalCode, preferredFirstName, preferredLastName, preferredMiddleName, preferredSuffix, publicDirectoryAttributes, selfPhone, selfPostalAddress, showInPublicDirectory, sn, st, street, street1, street2, studentConfidential, studentLevelCode, subjectId, suppressAll, suppressDisplay, suppressEmployeeDisplay, suppressedAttribute, targetedMembership, telephoneNumber, title, udcIdentifier, uid, uidNumber, undergraduateLevel, userCertificate, userPassword, userSMIMECertificate, username, uupid, virginiaTechAffiliation, virginiaTechID ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/delta/viewable-person-attributes' -i -X POST \
-d 'attribute=displayName&attribute=mailPreferredAddress'
Example Response
POST /v1/services/delta/viewable-person-attributes HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 52
attribute=displayName&attribute=mailPreferredAddress
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 148
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "No enum constant edu.vt.middleware.ed.model.db.LdapPersonAttributeDef.ALL"
}
Remove Viewable Person Attribute
DELETE /v1/services/{uusid}/viewable-person-attributes/{attribute}
Removes the given viewable person attribute from a service.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
|
Viewable person attribute. Must be one of: [ academicLevel, accountCheckupDate, accountCreationDate, accountExpirationDate, accountShelveDate, accountSponsor, accountState, accountTransition, authId, bannerName, bannerPIDM, c, campus, channel, city, classLevel, classLevelCode, cn, coalitionID, college, creationDate, dateOfBirth, deceasedFlag, degreeType, department, departmentNumber, displayName, eduPersonAffiliation, eduPersonAssurance, eduPersonEntitlement, eduPersonNickname, eduPersonOrcid, eduPersonOrgDN, eduPersonOrgUnitDN, eduPersonPrimaryAffiliation, eduPersonPrimaryOrgUnitDN, eduPersonPrincipalName, eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonUniqueId, employeeConfidential, employeeOffCampus, facsimileTelephoneNumber, gender, gidNumber, givenName, googleMailbox, groupMembership, groupMembershipUugid, guestId, hokiesPassword, homeDirectory, homeFax, homeMobile, homePager, homePhone, homePostalAddress, instantMessagingID, isMemberOf, l, labeledURI, lastEnrollmentTerm, lastEnrollmentTermCode, localFax, localMobile, localPager, localPhone, localPostalAddress, mail, mailAccount, mailAccountState, mailAlias, mailAuxiliaryAccount, mailDisplayAddress, mailExternalAddress, mailForwardingAddress, mailPreferredAddress, mailStop, major, majorCode, middleName, mobile, modificationDate, networkPassword, nextEnrollmentTerm, nextEnrollmentTermCode, objectClass, ou, pager, pairwiseId, passwordChangeDate, passwordExpirationDate, passwordState, personType, postOfficeBox, postalAddress, postalCode, preferredFirstName, preferredLastName, preferredMiddleName, preferredSuffix, publicDirectoryAttributes, selfPhone, selfPostalAddress, showInPublicDirectory, sn, st, street, street1, street2, studentConfidential, studentLevelCode, subjectId, suppressAll, suppressDisplay, suppressEmployeeDisplay, suppressedAttribute, targetedMembership, telephoneNumber, title, udcIdentifier, uid, uidNumber, undergraduateLevel, userCertificate, userPassword, userSMIMECertificate, username, uupid, virginiaTechAffiliation, virginiaTechID ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/foxtrot/viewable-person-attributes/sn' -i -X DELETE
Example Response
DELETE /v1/services/foxtrot/viewable-person-attributes/sn HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Endpoint
POST /v1/services/{uusid}/endpoints
Adds a service endpoint.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Endpoint communication protocol. Must be one of: [ CAS, HTTP, LDAP, OAUTH2, OIDC, SAML2 ] |
|
false |
Endpoint location URI. |
|
true |
Binding; required when protocol is SAML2. |
|
true |
Optional protocol-specific kind, e.g. "AssertionConsumerService" for a SAML endpoint. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/heh/endpoints' -i -X POST \
-d 'protocol=OAUTH2&location=https%3A%2F%2Fexample.org%2Foauth2_callback'
Example Response
POST /v1/services/heh/endpoints HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68
protocol=OAUTH2&location=https%3A%2F%2Fexample.org%2Foauth2_callback
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 177
{
"type" : "MissingServletRequestParameterException",
"code" : 400,
"message" : "Required request parameter 'protocol' for method parameter type Protocol is not present"
}
Remove Endpoint
DELETE /v1/services/{uusid}/endpoints/{id}
Removes a service endpoint.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
|
Unique ID of endpoint to remove. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/het/endpoints/33' -i -X DELETE
Example Response
DELETE /v1/services/het/endpoints/33 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Endpoint with ID 8675309 not found"
}
Password
POST /v1/services/{uusid}/password/{action}
Updates the password for the given service. This operation is formulated as an operational endpoint since password management is a write-only operation; thus it makes no sense to model it as a sub-resource collection. e.g. /services/a-service/passwords/123
, where CRUD operations are implied.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of service to update. |
|
Action to take on the service password: |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/add.self-service/password/add' -i -X POST
Example Response
POST /v1/services/add.self-service/password/add HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Certificate
POST /v1/services/{uusid}/certificates
Adds a certificate to the given service.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of the service to update. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
PEM encoded X.509 certificate. |
|
true |
Optional usage criteria. One of [ auth, enc, sig ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/middleware-test/certificates' -i -X POST \
-d 'pem=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----&use=sig'
Example Response
POST /v1/services/middleware-test/certificates HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 1512
pem=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----&use=sig
Example Error Response
HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 148
{
"type" : "FoundException",
"code" : 409,
"message" : "Certificate with ID 486111850375927026925710017908841856405105970101 already exists"
}
Remove Certificate
DELETE /v1/services/{uusid}/certificates/{serial}
Removes the certificate with the given serial from the given service.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Path Parameters
Parameter | Description |
---|---|
|
ID of the service to update. |
|
Serial number in decimal representation. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/middleware-test/certificates/486111850375927026925710017908841856405105970101' -i -X DELETE
Example Response
DELETE /v1/services/middleware-test/certificates/486111850375927026925710017908841856405105970101 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Certificate with ID 123456 not found"
}
Manage Attribute Aliases
PATCH /v1/services/z-service
Sample patch demonstrating how to manage attribute aliases. Use of the test operation is strongly recommended to ensure indices have not changed under concurrency.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].
Example Request
$ curl 'https://api.middleware.vt.edu/v1/services/z-service' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/attributeAliases/0/alias","value":null},{"op":"replace","path":"/attributeAliases/1/alias","value":"mailPreferredAddress"},{"op":"test","path":"/attributeAliases/2/name","value":"uupid"},{"op":"replace","path":"/attributeAliases/2/alias","value":"username"}]'
Example Response
PATCH /v1/services/z-service HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 284
Host: api.middleware.vt.edu
[{"op":"replace","path":"/attributeAliases/0/alias","value":null},{"op":"replace","path":"/attributeAliases/1/alias","value":"mailPreferredAddress"},{"op":"test","path":"/attributeAliases/2/name","value":"uupid"},{"op":"replace","path":"/attributeAliases/2/alias","value":"username"}]
Example Error Response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Token Resource API
Send OTP
POST /v1/tokens
Creates a token with a 6-digit OTP and sends the code to a recipient given by any of the following parameters: -email
- email address - sms
- mobile phone number (via SMS) - voice
- phone number (via phone call). At least one of the above parameters is required. If multiple parameters are provided, only the first from the list above is used (in that order).
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Purpose of token. Must be one of: [ ACCOUNT_ACTIVATION, ACCOUNT_CREATION, AUTHENTICATION, PASSWORD_RESET ] |
|
true |
Optional token type; MUST be "otp" if provided. |
|
true |
OTP recipient email address. |
|
true |
OTP recipient mobile phone number. |
|
true |
OTP recipient phone number. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/tokens' -i -X POST \
-d 'type=otp&email=somebody%40gmail.com&scope=password_reset'
Example Response
POST /v1/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 56
type=otp&email=somebody%40gmail.com&scope=password_reset
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 190
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'no_such_thing'. Valid types: [ ACCOUNT_CREATION, ACCOUNT_ACTIVATION, AUTHENTICATION, PASSWORD_RESET ]"
}
Validate
GET /v1/tokens/{id}
Validates a token by looking it up by ID/handle and verifying that it is still within its validity period.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].
Path Parameters
Parameter | Description |
---|---|
|
Token identifier/handle. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/tokens/FpsLWEcf5YpMULQa91cq25x2Hqk' -i -X GET
Example Response
GET /v1/tokens/FpsLWEcf5YpMULQa91cq25x2Hqk HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Validate OTP
GET /v1/tokens
Validates an OTP by looking up the token that bears it and ensuring it is within its validity period. The recipient address where the OTP was delivered may be specified by either an email address or a phone number, but one or the other is required.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
OTP code. |
|
|
Email address of OTP recipient. |
|
|
Phone number of OTP recipient. |
Example Request
$ curl 'https://api.middleware.vt.edu/v1/tokens?code=718359&email=somebody%40example.com' -i -X GET
Example Response
GET /v1/tokens?code=718359&email=somebody%40example.com HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 401 Unauthorized
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 90
{
"type" : "CredentialExpiredException",
"code" : 401,
"message" : "Expired token"
}
User Resource API
Fetch
GET /v2/users/{uid}
Fetches the user with the given unique identifier.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user to fetch. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Zero or more optional sections of fields to include in fetched user resource. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/7100001?with=all' -i -X GET
Example Response
GET /v2/users/7100001?with=all HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99
{
"type" : "NotFoundException",
"code" : 404,
"message" : "User with ID 12345671 not found"
}
Fetch Property
GET /v2/users/{uid}/{property}
Fetches a collection of subordinate resources of a user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user to fetch. |
|
Sub-resource collection of the user to be fetched. Must be one of: [ ADDRESSES, AFFILIATIONS, CERTIFICATES, EMAILS, IDENTIFIERS, IMIDS, MAILBOXES, NAMES, PHONES, SUPPRESSIONS, URIS ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012267/addresses' -i -X GET
Example Response
GET /v2/users/20012267/addresses HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 228
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'employee'. Valid types: [ ADDRESSES, AFFILIATIONS, CERTIFICATES, EMAILS, IDENTIFIERS, IMIDS, MAILBOXES, NAMES, PHONES, SUPPRESSIONS, URIS ]"
}
Query
GET /v2/users
Fetches a collection of user resources based on query terms.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
User affiliation |
|
|
External email address of type APPLICANT_EMAIL |
|
|
External email address of any type |
|
|
First name |
|
|
Last name |
|
|
Mailbox primary or alias |
|
|
Associated person uid |
|
|
Phone number |
|
|
Banner PIDM |
|
|
Sponsor of the service account |
|
|
Account identifier, username or email |
|
|
Virginia Tech ID |
|
|
Zero or more optional sections of fields to include in fetched user resources. |
|
|
Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided. |
|
|
Size of the page you want to retrieve. Must be greater than 0. |
|
|
How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users?with=all&last=jones&page=3&size=2&sort=id%2Casc' -i -X GET
Example Response
GET /v2/users?with=all&last=jones&page=3&size=2&sort=id%2Casc HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Create HA
POST /v2/users
Creates a user with high identity assurance that is uniquely identified in Banner by the given PIDM.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Banner PIDM. No validation is performed on this value other than basic character set check. |
|
false |
Person first name. |
|
false |
Person last name. |
|
false |
Set of user affiliations. |
|
true |
Person name prefix/title of address, e.g. Mr., Ms., His Excellency. |
|
true |
Person middle name. |
|
true |
Person name suffix, e.g. Jr, Sr., III. |
|
true |
Birth date. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users' -i -X POST \
-d 'pidm=51234&first=Baden&last=Powell&prefix=Sir&affiliation=VT-ACTIVE-MEMBER&affiliation=VT-FACULTY'
Example Response
POST /v2/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 97
pidm=51234&first=Baden&last=Powell&prefix=Sir&affiliation=VT-ACTIVE-MEMBER&affiliation=VT-FACULTY
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Create LA
POST /v2/users
Creates a user with low identity assurance.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Person first name. |
|
false |
Person last name. |
|
false |
Set of user affiliations. |
|
true |
Person name prefix/title of address, e.g. Mr., Ms., His Excellency. |
|
true |
Person middle name. |
|
true |
Person name suffix, e.g. Jr, Sr., III. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users' -i -X POST \
-d 'first=Fuzzy&middle=Little&last=Lumpkins&affiliation=VT-GUEST'
Example Response
POST /v2/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 60
first=Fuzzy&middle=Little&last=Lumpkins&affiliation=VT-GUEST
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Delete
DELETE /v2/users/{uid}
Deletes the user. Person is not deleted.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012146' -i -X DELETE
Example Response
DELETE /v2/users/20012146 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106
{
"type" : "NotFoundException",
"code" : 404,
"message" : "User with ID 896745232435657 not found"
}
Link
POST /v2/users/{uid}/link/{personUid}
Associates a user with a different person using a type-specific merging strategy.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user to link. |
|
UID of person to associate with the user. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012280/link/20012277' -i -X POST
Example Response
POST /v2/users/20012280/link/20012277 HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Certificate
POST /v2/users/{uid}/certificates
Adds an X.509 or S/MIME certificate to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Type of certificate. Must be one of: [ SMIME, X509 ] |
|
false |
PEM-encoded certificate. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012095/certificates' -i -X POST \
-d 'type=SMIME&cert=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----'
Example Response
POST /v2/users/20012095/certificates HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 1516
type=SMIME&cert=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Remove Certificate
DELETE /v2/users/{uid}/certificates/{type}
Deletes a certificate determined by the given type.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Type of certificate. Must be one of: [ SMIME, X509 ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20011661/certificates/x509' -i -X DELETE
Example Response
DELETE /v2/users/20011661/certificates/x509 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Certificate with ID X509 not found"
}
Add External Email Address
POST /v2/users/{uid}/emails
Adds an external email address to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Type of external address. [ appl = applicant, dsp = display email, prc = password recovery email, vcm = VCOM email ]. Must be one of: [ APPL, DSP, PRC, VCM ] |
|
false |
External email address to add. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012606/emails' -i -X POST \
-d 'type=DSP&address=Hammy%40icloud.com'
Example Response
POST /v2/users/20012606/emails HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 35
type=DSP&address=Hammy%40icloud.com
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 131
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'GST'. Valid types: [ APPL, DSP, PRC, VCM ]"
}
Remove External Email Address
DELETE /v2/users/{uid}/emails/{typeCode}
Deletes the given type of external email address from the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Identifier type to remove. [ appl = applicant, dsp = display email, prc = password recovery email, vcm = VCOM email ]. Must be one of: [ APPL, DSP, PRC, VCM ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012476/emails/prc' -i -X DELETE
Example Response
DELETE /v2/users/20012476/emails/prc HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 131
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'gst'. Valid types: [ APPL, DSP, PRC, VCM ]"
}
Add Identifier
POST /v2/users/{uid}/identifiers
Adds an identifier to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Identifier type to add. Must be one of: [ COAID, PAIRWISEID, PIDM, UDCID, VTID ] |
|
false |
Value (ID) of the new identifier. |
|
false |
Optional context that conveys the relying party identifier to which the given pairwise ID is targeted. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012386/identifiers' -i -X POST \
-d 'type=pairwiseid&id=ES4F6ESDBPVVHS7ZXRAV2ZJKASDR25KMZLVKSJKJXKWZ42N63PMA%3D%3D%3D%3D%40vt.edu&context=service-a'
Example Response
POST /v2/users/20012386/identifiers HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 110
type=pairwiseid&id=ES4F6ESDBPVVHS7ZXRAV2ZJKASDR25KMZLVKSJKJXKWZ42N63PMA%3D%3D%3D%3D%40vt.edu&context=service-a
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 152
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'unknown'. Valid types: [ COAID, PIDM, UDCID, VTID, PAIRWISEID ]"
}
Remove Identifier
DELETE /v2/users/{uid}/identifiers/{type}
Deletes the given type of identifier from the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Identifier type to remove. Must be one of: [ COAID, PAIRWISEID, PIDM, UDCID, VTID ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012429/identifiers/coaid' -i -X DELETE
Example Response
DELETE /v2/users/20012429/identifiers/coaid HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 153
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'entityid'. Valid types: [ COAID, PIDM, UDCID, VTID, PAIRWISEID ]"
}
Add Address
POST /v2/users/{uid}/addresses
Adds an address of a particular type to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Type of address. Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ] |
|
true |
State/province code. |
|
true |
Flag to set whether the address should be published. True for unpublished. Defaults to false. |
|
true |
First part of street address. |
|
true |
Second part of street address. |
|
true |
Third part of street address. |
|
true |
Post office box. |
|
true |
City name. |
|
true |
Postal code. |
|
true |
ISO 3166 (alpha-2) country code.See <a>https://www.iso.org/obp/ui/#search</a> for a list. |
|
true |
MailStop (4 digit number). |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20011802/addresses' -i -X POST \
-d 'type=office&unlisted=true&street1=1700+Pratt+Drive&street2=Andrews+Information+Building&street3=Room+111&pobox=1234&city=Blacksburg&state=VA&zip=24060&country=US'
Example Response
POST /v2/users/20011802/addresses HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 161
type=office&unlisted=true&street1=1700+Pratt+Drive&street2=Andrews+Information+Building&street3=Room+111&pobox=1234&city=Blacksburg&state=VA&zip=24060&country=US
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Remove Address
DELETE /v2/users/{uid}/addresses/{type}
Deletes the address of the given type from the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Address type to remove. Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20011742/addresses/local' -i -X DELETE
Example Response
DELETE /v2/users/20011742/addresses/local HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Update Address
PATCH /v2/users/{uid}/addresses/{type}
Updates a user’s address.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Type of address. Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012231/addresses/home' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/street1","value":"My New St."},{"op":"replace","path":"/street2","value":"New Street 2"},{"op":"replace","path":"/unlisted","value":true}]'
Example Response
PATCH /v2/users/20012231/addresses/home HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 164
Host: api.middleware.vt.edu
[{"op":"replace","path":"/street1","value":"My New St."},{"op":"replace","path":"/street2","value":"New Street 2"},{"op":"replace","path":"/unlisted","value":true}]
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 98
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Address with ID HOME not found"
}
Add Name
POST /v2/users/{uid}/names
Adds a name to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Type of name. Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ] |
|
false |
First name. |
|
false |
Last name. |
|
true |
Name prefix. |
|
true |
Middle name. |
|
true |
Name suffix. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012058/names' -i -X POST \
-d 'type=preferred&first=john&last=doe&prefix=Mr.&suffix=Jr.&middle=deer'
Example Response
POST /v2/users/20012058/names HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68
type=preferred&first=john&last=doe&prefix=Mr.&suffix=Jr.&middle=deer
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 158
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'unknown'. Valid types: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]"
}
Remove Name
DELETE /v2/users/{uid}/names/{type}
Deletes the given type of name from the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Name type to remove. Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20011863/names/preferred' -i -X DELETE
Example Response
DELETE /v2/users/20011863/names/preferred HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 158
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'unknown'. Valid types: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]"
}
Update Name
PATCH /v2/users/{uid}/names/{type}
Updates the name based on the given type.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Name type to update. Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ] |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012301/names/preferred' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/first","value":"Alice"},{"op":"replace","path":"/last","value":"Adams"}]'
Example Response
PATCH /v2/users/20012301/names/preferred HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 98
Host: api.middleware.vt.edu
[{"op":"replace","path":"/first","value":"Alice"},{"op":"replace","path":"/last","value":"Adams"}]
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Name with ID EXTERNAL not found"
}
Add Phone
POST /v2/users/{uid}/phones
Adds a self-reported phone number to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Phone number digits. |
|
false |
Phone number type. Must be one of: [ FAX, HOME, LOCAL, MOBILE, OFFICE, PAGER, SELF_REPORTED, SMS ] |
|
true |
ISO 3166 (alpha-2) country code. See <a>https://www.iso.org/obp/ui/#search</a> for a list. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/2443257202524752/phones' -i -X POST \
-d 'type=SELF_REPORTED&number=33511223344&country=FR'
Example Response
POST /v2/users/2443257202524752/phones HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 48
type=SELF_REPORTED&number=33511223344&country=FR
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Remove Phone
DELETE /v2/users/{uid}/phones/{phoneUid}
Deletes the given phone number.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Unique identifier of phone number to delete. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/2443252526539641/phones/56' -i -X DELETE
Example Response
DELETE /v2/users/2443252526539641/phones/56 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Phone with ID 1234567 not found"
}
Update Phone
PATCH /v2/users/{uid}/phones/{phoneUid}
Updates the given phone number.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Unique identifier of phone number to update. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/2443231480655655/phones/48' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/countryCode","value":"MX"}]'
Example Response
PATCH /v2/users/2443231480655655/phones/48 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 53
Host: api.middleware.vt.edu
[{"op":"replace","path":"/countryCode","value":"MX"}]
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92
{
"type" : "AuthorizationDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Add Social Identifier
POST /v2/users/{uid}/{type}
Adds an instant messaging ID/website to the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Social identifier type to add. Must be one of: [ IMIDS, URIS ] |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Key:value ID Instant Messaging id:somebody@im.vt.edu. - Website:`[label]:[uri]` e.g, Web Site:http://www.vt.edu. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012223/uris' -i -X POST \
-d 'id=awesome%3Ahttp%3A%2F%2Fnewgrounds.com'
Example Response
POST /v2/users/20012223/uris HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 40
id=awesome%3Ahttp%3A%2F%2Fnewgrounds.com
Example Error Response
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85
{
"type" : "AccessDeniedException",
"code" : 403,
"message" : "Access Denied"
}
Remove Social Identifier
DELETE /v2/users/{uid}/uris/{id}
Deletes the imid or website from the user.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
|
Id of the social identifier to remove. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012312/uris/115' -i -X DELETE
Example Response
DELETE /v2/users/20012312/uris/115 HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 95
{
"type" : "NotFoundException",
"code" : 404,
"message" : "Contact with ID 1 not found"
}
Is Eligible
GET /v2/users/{uid}/eligibility
Determines the eligibility for various items.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Query Parameters
Parameter | Optional | Description |
---|---|---|
|
|
Eligibility item to be checked. If not provided, returns eligibility for all the items in the following list.class edu.vt.middleware.ed.service.UserManager$EligibilityItem |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012785/eligibility?for=TWO_FACTOR' -i -X GET
Example Response
GET /v2/users/20012785/eligibility?for=TWO_FACTOR HTTP/1.1
Host: api.middleware.vt.edu
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 192
{
"type" : "IllegalArgumentException",
"code" : 400,
"message" : "Invalid type 'invalid-item'. Valid types: [ HOKIES_SECRET, NETWORK_SECRET, RECOVERY_OPTIONS, TWO_FACTOR, VT_ACCOUNT ]"
}
Update User
PATCH /v2/users/{uid}
Updates a user; only the Person#getSuppressAll()
field may be updated by this method.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/2443253749071976' -i -X PATCH \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/suppressAll","value":true}]'
Example Response
PATCH /v2/users/2443253749071976 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 53
Host: api.middleware.vt.edu
[{"op":"replace","path":"/suppressAll","value":true}]
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104
{
"type" : "UnsupportedOperationException",
"code" : 400,
"message" : "Cannot patch given field"
}
Validate SSN
POST /v2/users/{uid}/ssn/validate
Validates the last four digits of a user’s SSN.
Authorization
One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].
Path Parameters
Parameter | Description |
---|---|
|
UID of user. |
Form Parameters
Parameter | Optional | Description |
---|---|---|
|
false |
Last four digits of SSN. |
Example Request
$ curl 'https://api.middleware.vt.edu/v2/users/20012164/ssn/validate' -i -X POST \
-d 'ssn=9630'
Example Response
POST /v2/users/20012164/ssn/validate HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 8
ssn=9630
Example Error Response
HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 90
{
"type" : "NotFoundException",
"code" : 404,
"message" : "SSNHash does not exist"
}
Known Breaking Changes
The following section describes API changes from ED 4.x to ED 5.x. If we deemed the API to be interface compatible, the version number is unchanged; otherwise the version number incremented accordingly. The mailbox and account APIs changed dramatically as a consequence of need to evolve the data model, and these have been incremented to /v2.
General API Behavior Changes
-
Deletion: DELETE operations now return a 204 instead of a 200. This provides a clear signal that there is no content in the body to read.
-
Pagination: The parameters start and stop are no longer supported. All clients should use page and size instead. The meaning of the parameters is also different. In ED4 start:stop meant: fetch rows from index[start] to index[stop]. In this version of ED page:size means: fetch a page with -size- number of results:
-
Page=1 : Size=20 → fetch the first 20 results (1-20)
-
Page=2 : Size=20 → fetch the next 20 results (21-40)
-
Type Codes
Type codes have changed throughout the API to increase readability. The following table provides a mapping from the ED4 value to that of ED5.
Type |
ED4 |
ED5 |
Notes |
Third-Party Email |
APPL |
APPLICANT_EMAIL |
|
Third-Party Email |
DSP |
DISPLAY_EMAIL |
|
Third-Party Email |
GST |
N/A |
Guest email address is an account attribute in ED5 |
Third-Party Email |
PRC |
NOTIFICATION_EMAIL |
|
Third-Party Email |
VCM |
VCOM_EMAIL |
|
Name |
AN |
ALUMNI |
|
Name |
BN |
BANNER |
|
Name |
PN |
PREFERRED |
|
Person |
Virginia Tech |
VT |
|
Person |
Guest |
GUEST |
|
Person |
Sponsored |
N/A |
Sponsor is an optional account attribute in ED5 |
Recovery |
C4H |
N/A |
Call 4-Help is a materialized field in ED5: |
Recovery |
O2S |
OTP2SMS |
|
Recovery |
O2V |
OTP2VOICE |
|
Recovery |
GRA |
||
Recovery |
YRA |
YAHOO |
|
State |
ACT |
ACTIVE |
|
State |
LKD |
LOCKED |
|
State |
PVD |
UNCREDENTIALED |
|
State |
SLD |
SHELVED |
|
State |
TBR |
TO_BE_DELETED |
Account Resource API
-
Version is now v2.
-
The URI for managing account token credentials is now
/v2/accounts/tokens
; it was formerly/v1/tokens
.
Mailbox Resource API
-
Version is now v2.
-
Mailbox fetch and query JSON structures have changed:
-
passwordChangeDate
andpasswordState
fields have been removed because mailboxes no longer have passwords. -
nextStateChangeDate
is deprecated. An approximation of the ED4 calculation is used. -
routeType
which was undefined in ED4 is nowRouteType.NONE
. The JSON for this field is now "None" rather than null.
-
-
Mailbox delete will throw a 404 when attempting to remove an alias that does not exist on the given mailbox.
Password Complexity API
Password rules are now returned in an array, even when type is specified.
Guest Resource API
There is no longer a dedicated endpoint for managing guests. All guest operations have been assumed by either the person API (managing demographic data) and the account API (credential creation/management). See the Invite Guest section above for the new API for sending invites to create guest accounts.