This document provides information about the MCommunityGidNumber application programming interface (API). The MCommunityGidNumber API is a web service that IT professionals can use to reserve gid numbers for groups. 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 MCommunityGidNumber API is a web service that IT professionals can use to reserve gid numbers for groups. A gid number is used in Unix/Linux systems as a unique identifier for a group. This service enables reservation of gid 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 MCommunityGidNumber 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 MCommunityGidNumber.
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 MCommunityGidNumber API.
-
Subscribe to the MCommunityGidNumber 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 response listed below.
| Input Parameter | Definition | Data type | Example |
|---|---|---|---|
| Administrator (uniqname) | The uniqname of the reference person responsible for maintaining the group to which the gidNumber is assigned. Multiple people can be listed here. | string | bjensen |
| System | The name of the server or system in which the group will be used. | string | limburger.dsc.umich.edu (server) MiWorkspace (system) |
| Foreign Key | Group name. If an MCommunity group, use the group email value without the @umich.edu. For non-MCommunity groups, enter the group name. | string | groupname |
| Description | Provides a description for the gidNumber | string | MiWorkspace GID Number MCommunity Group gidNumber Reserved for MCIT |
Sample Request and Output
Requesting a gidNumber for a system.
Format of request:
Example request:
MCommunity+Test+Group&description=MCommunity+Group+gidNumber
Sample output:
"idNumber": {
"dn": "umichGidNumber=2600007,ou=gidNumbers,o=Registry",
"adminUid": "bjensen",
"idNumber": "2600007",
"description": "MCommunity Group gidNumber"
}
}
Output Definitions
| Output | Definition | Data type | Example |
|---|---|---|---|
| dn | The fully qualified distinguished name (dn) of the gidNumber object in the MCommunity LDAP tree. | DN | umichGidNumber=2600007,ou=gidNumbers,o=Registry |
| adminUid | The uniqname of one or more people who own this gidNumber. | string | bjensen |
| idNumber | The gidNumber for this group. | string | 2600007 |
| description | The description that will be stored in MCommunity for this gidNumber. | string | MCommunity Group gidNumber |