This document provides information about the MCommunityUidNumber application programming interface (API). The MCommunityUidNumber API is a web service that IT professionals can use to reserve uid numbers for accounts. Instructions on making a request, available input parameters, and potential outputs and definitions are detailed in this document. This document assumes a basic understanding of the U-M API Directory. See the Help page on the API Directory website for information about the API Directory.
About the API
The MCommunityUidNumber API is a web service that IT professionals can use to reserve uid numbers for administrative accounts. A uid number is used in Unix/Linux systems as a unique identifier for an account. This service enables reservation of uid numbers in a way that avoids overlap with ones assigned by the ITS MCommunity team and others.
The API is restricted to 60 calls per minute. The MCommunityUidNumber API supports JSON (JavaScript Object Notation).
Use the ITS Service Status page to stay informed about potential outages of this web service.
Making a Request
The API is located in the API Directory as MCommunityUidNumber.
First, register your application in the API Directory.
-
Log in to the API Directory with your uniqname and UMICH password.
-
Register your application with the API Directory by adding it as a new application.
Then, follow these steps to make a request.
-
On the API Directory site, navigate to the MCommunityUidNumber API.
-
Subscribe to the MCommunityUidNumber API by selecting your application in the drop-down list. Note your consumer key and consumer secret.
-
Use your consumer key and consumer secret obtained in step two to generate an access token either:
-
Programmatically within your application (see Generating and Renewing Access Tokens)
-
Or on the subscription page for your application
By default, access tokens are available for one hour.
-
-
Make a request using the appropriate input parameters and the sample request and output listed below.
| Input Parameter | Definition | Data type | Example |
|---|---|---|---|
| Administrator (uniqname) | The uniqname of the reference person responsible for maintaining the identity, not the person to whom the uidNumber is assigned. Multiple people can be listed here. | string | bjensen |
| System | The name of the server or system in which the admin account will be used. | string | limburger.dsc.umich.edu (server) MiWorkspace (system) |
| Foreign Key | Account name. The name or user ID of the admin account which will be assigned the uidNumber. | string | bjensen1 |
| Description | Brief description of how the admin account will be used. | string | File attach ID for MCommDev MiWorkspace admin account Shared account for research group |
Sample Request and Output
Requesting a uidNumber for a system.
Format of request:
GET http://api-gw.it.umich.edu/MCommunityUidNumber/v1?adminUid={input}&system={input}&foreignkey={input}&description={input}
Example request:
?adminUid=bjensen&system=limburger.dsc.umich.edu&foreignkey=bjensen1&description=Shared+account+for+research+group
Sample output:
{
"idNumber": {
"description": "Shared account for research group",
"idNumber": "1000208",
"adminUid": "bjensen",
"dn": "umichUidNumber=1000208,ou=uidNumbers,o=Registry"
}
}
Output Definitions
| Output | Definition | Data type | Example |
|---|---|---|---|
| description | The description that will be stored in MCommunity for this uidNumber. | string | Shared account for research group |
| idNumber | The uidNumber for this account. | string | 1000208 |
| adminUid | The uniqname of one or more people who own this uidNumber. | string | bjensen |
| dn | The fully qualified distinguished name (dn) of the uidNumber object in the MCommunity LDAP tree. | DN | umichUidNumber=1000208,ou=uidNumbers,o=Registry |