Skip to main content

Getting Started with the MaIS Web APIs

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:

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

  • construct p12 or keystore for accessing webservice
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:

  1. The URL must conform to the API. The example above breaks, but you will want to make sure it is all one line.
  2. example-private.key is the key file you used to create you CSR to obtain a MaIS certificate.
  3. 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.
  4. File paths must be correct.
  5. 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:

  1. Get the extension by using tools > add-ons from the file menu.
  2. Search for and install the Poster add on, currently version 3.1.0.
  3. 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.
  4. File paths must be correct.
  5. 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.
Last modified