Account RESTful Web Service API

The Account web service provides a way to retrieve lists of accounts and account details given a SUNet ID.

This includes:

Getting Single Account details given a SUNet ID
List of accounts that changed status in past x days
Support shortcut URLS — Active/Inactive SELF and FUNCTIONAL accounts

How to get started with the Account API

Follow the Middleware and Integration Services Integration (MaIS) checklist for RESTful Web Services. If you need help, are not sure whether the Web APIs are the best method for integrating with the registry, or just have some questions, contact the MaIS team.

HTTP Status codes

Code	Conditions
200 OK	The usual successful return code.
400 Bad Request	Missing required parameters or identifier is in wrong format.
403 Access Denied	The request was made without valid certificate.
404 Not Found	The record you're looking for doesn't exist.
500 Internal Server Error	Something broke with our code. Please tell us about it.

Error Handling

Account API sends error status via standard HTTP status codes (4xx or 5xx) and always returns an XML/JSON document detailing the error.

An example of XML error document:

<AccountWsError>
   <status>404</status>
   <message>Account [xxxxx] not found</message>
   <url>https://accountws.stanford.edu/accounts/xxxxx</url>
</AccountWsError>

An example of JSON error document:

{
"status": 400,
"message": "Valid number of 'statusdays' is 1..30",
"url": "https://accountws.stanford.edu/accounts?type=self&status=inactive&statusdays=355"
}

Return format

There are 2 formats Accountws supports, XML and JSON. By default, the return format is JSON if no Accept header is specified. User can also specify application/json as the Accept header to receive JSON. In browsers, the default Accept header is application/xml so data is returned in XML format.

Get Single Account details

Description	Get Single Account details by sunetid or functional account name. The data can be full/lite data.
URL	Full Data - https://accountws.stanford.edu/accounts/{id} Lite Data - https://accountws.stanford.edu/accounts/lite/{id}
UAT URL	Full Data - https://accountws-uat.stanford.edu/accounts/{id} Lite Data - https://accountws-uat.stanford.edu/accounts/lite/{id}
Method	GET
Returns	200 & Account details
	403 & Not authorized to access the service.
	404 & error: id is invalid.

Id should be sunetid.

List of accounts that changed status in past x days

Description	List of active/inactive accounts of which the status has changed in the past x days. (returns only lite format)
URL	https://accountws.stanford.edu/accounts?type={type}&status={status}&statusdays={days}
UAT URL	https://accountws-uat.stanford.edu/accounts?type={type}&status={status}&statusdays={days}
Query String	type - self/functional status - active/inactive/pending days - 1 to 30
Method	GET
Returns	200 & List of active/inactive accounts in lite format
	403 & error: Not authorized to access the service.
	404 & error: Input invalid.

Support shortcut URLS - Active/Inactive SELF accounts

Description	Support shortcut URLS for active/inactive SELF accounts that changed status in the last 7/30 days. (returns only lite format)
URL	https://accountws.stanford.edu/accounts/selfactive7days https://accountws.stanford.edu/accounts/selfactive30days https://accountws.stanford.edu/accounts/selfinactive7days https://accountws.stanford.edu/accounts/selfinactive30days
UAT URL	https://accountws-uat.stanford.edu/accounts/selfactive7days https://accountws-uat.stanford.edu/accounts/selfactive30days https://accountws-uat.stanford.edu/accounts/selfinactive7days https://accountws-uat.stanford.edu/accounts/selfinactive30days
Method	GET
Returns	200 & List of active/inactive SELF accounts
	403 & error: Not authorized to access the service.
	404 & error: Input invalid.

Support shortcut URLS - Active/Inactive FUNCTIONAL accounts

Description	Support shortcut URLS for active/inactive FUNCTIONAL accounts that changed status in the last 7/30 days. (returns only lite format)
URL	https://accountws.stanford.edu/accounts/funcactive7days https://accountws.stanford.edu/accounts/funcactive30days https://accountws.stanford.edu/accounts/funcinactive7days https://accountws.stanford.edu/accounts/funcinactive30days
UAT URL	https://accountws-uat.stanford.edu/accounts/funcactive7days https://accountws-uat.stanford.edu/accounts/funcactive30days https://accountws-uat.stanford.edu/accounts/funcinactive7days https://accountws-uat.stanford.edu/accounts/funcinactive30days
Method	GET
Returns	200 & List of active/inactive FUNCTIONAL accounts
	403 & error: Not authorized to access the service.
	404 & error: Input invalid.