The Middleware and Integration Services (MaIS) team provides several web services that allow access to the Registry though web APIs. These can be used by university applications to gather data from various registry sources.
Web services available
The following web services are available:
- Account
- CourseClass
- Person
- Privilege (Authority)
- Student
- Workgroup
- Workgroup - API Gateway
- Workgroup - API Gateway (JSON)
Getting Started Checklist
| Recommended | Task | Actor |
|---|---|---|
| Review the MaIS Data Usage and Integration Policies. | Client | |
| Contact MaIS to discuss requirements via Jira/ServiceNow request | MaIS, Client | |
| Seek data owner approval - where applicable | Client | |
| Update Jira/ServiceNow request with data-owner approvals (if applicable) | MaIS or client | |
| Client to request certificates (non-prod and prod) via Registrycm | Client | |
| Sign certificates, and review selection of services before signing | MaIS | |
|
Download certificates
|
Client | |
| Workgroup service API specific: for existing workgroup access — add certificate as a workgroup admin | Client | |
| Workgroup service API specific: to enable workgroup creation - add certificate as a member of the stem | MaIS | |
| Develop the software to connect to the API | MaIS or Client |
Security
All of the current MaIS web services use an x509 certificate to control access. You will need to create a certificate signing request (CSR) and then submit that to the MaIS team. The MAIS team will then sign the request and send you a certificate file. You will then need to use that certificate with your code to access the web service.
Certificate Manager
To submit your CSR, please visit our Certificate Manager website. Access to Certificate Manager is restricted to members of the Stanford Administrative community. Complete step 1, 'Complete the request [Other systems]'. If you need additional assistance please feel free to contact us via HelpSU link at the bottom of the page.
More information and examples
Below are some examples of ways to access the web service.
Using a curl command
The use of curl from a server command line is really only useful for testing connectivity between that server and the web service. The command will do a GET operation and return an XML file. You should also note that you will have to use the certificate password and that once you have issued the command, received the result, and finished testing you should clear the command line history.
curl -k --dump -G --key /etc/example-private.key --cert /etc/example.pem:password https://workgroupsvc-uat.stanford.edu/v1/workgroups/example:demo
Additional instructions:
- The URL must conform to the API. The example above breaks, but you will want to make sure it is all one line.
- example-private.key is the key file you used to create you CSR to obtain a MaIS certificate.
- example.pem:password consists of two parts divided by the colon.
- example.pem is the certificate you received from MaIS.
- password is the password used for the example-private.key file.
- File paths must be correct.
- File names must be correct.
Using the Poster Firefox or Chrome web browser plug-in
The following explains how to use the Firefox Poster.
Instructions to Install:
- Get the extension by using tools > add-ons from the file menu.
- Search for and install the Poster add on, currently version 3.1.0.
- Depending of the version of Firefox, there may a button on the tool-bar, Add-on toolbar.
- example.pem is the certificate you received from MaIS.
- password is the password used for the example-private.key file.
- File paths must be correct.
- File names must be correct.
Troubleshooting
My integration with Web Service is not working, what should I do?
If your integration with Web Service is not working, you should review the following:
- Verify that you are using a valid certificate (See the Certificate How-to)
- Double-check the URL for the web service.
- If using the Workgroup API, verify that your certificate is for the proper workgroup.
