Student RESTful Web Services API

The student web service allows for the retrieval of student and course data.

This includes getting:

A Student's Person XML
Student's Enrollment XML for current term
Student's Enrollment XML for a specific term
Student's Enrollment XML — all classes
Course and Class, just Course, just Class or Section XML

How to get started with the Student 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

Error handling works for all web services except student search.

Student API sends error status via standard HTTP status codes (4xx or 5xx) and always returns an XML document detailing the error. For example, when the client makes a call to get a person XML and the person's id is invalid, the system will return the following XML error document:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>404</code>
<message><![CDATA[Person resource xxxxx not found.]]></message>
</error>

Get student's person XML

Description	Get Person XML
URL	https://studentws.stanford.edu/v1/person/{personId}
UAT URL	https://studentws-uat.stanford.edu/v1/person/{personId}
Method	GET
Returns	200 & Person XML
	400 & error XML: personId's affiliation is not student.
	404 & error XML: personId is invalid.

personId could be univid, sunetid or regid.

Get student's enrollment XML for current term

Description	Get Enrollment XML for current term
URL	https://studentws.stanford.edu/v1/person/{personId}/enrollment/term
UAT URL	https://studentws-uat.stanford.edu/v1/person/{personId}/enrollment/term
Method	GET
Returns	200 & Enrollment XML
	400 & error XML: personId's affiliation is not student.
	404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Get student's enrollment XML for a term

Description	Get Enrollment XML for a term
URL	https://studentws.stanford.edu/v1/person/{personId}/enrollment/term/{termId}
UAT URL	https://studentws-uat.stanford.edu/v1/person/{personId}/enrollment/term/{termId}
Method	GET
Returns	200 & Enrollment XML
	400 & error XML: personId's affiliation is not student.
	404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Get student's enrollment XML — all classes

Description	Get Enrollment XML
URL	https://studentws.stanford.edu/v1/person/{personId}/enrollment
UAT URL	https://studentws-uat.stanford.edu/v1/person/{personId}/enrollment
Method	GET
Returns	200 & Enrollment XML
	400 & error XML: personId's affiliation is not student.
	404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Student search by qualifier, career, acadId, and returnType — plain text

Description	Search students for given qualifier, career, and acadId values. acadId parameter is optional. The method returns the student info in plain text. The web service returns the student data determined by returnType parameter, e.g., if returnType=sunetid, the search will return sunetid of all the students in plain text, one sunetid per line. Valid qualifier values are: contingent, incoming, ndo, nonactive, notregistered, onleave, postdoc, recent, and active. Valid career values are: gsb, med, law, gr, and ug. Valid returnType values are: regid, univid, card, directory, and sunetid. The default value for returnType is regid. Set accept header with value text/plain to access this web service. Method does not return XML in case of an error. Check return types for detail. Some combinations of parameters do not work, e.g., qualifier=incoming&returnType=card will return 404.
URL	https://studentws.stanford.edu/v1/person/search?qualifier=incoming&career=UG
UAT URL	https://studentws-uat.stanford.edu/v1/person/search?qualifier=incoming&career=UG
Method	GET
Query String	qualifier=incoming&career=UG
Returns	200 & persons ids
	400 & error string: required parameters qualifier and career are missing
	404 & error string: No person is found for given search criteria

Get courseclass XML

Description	Get courseclass XML by Id
URL	https://studentws.stanford.edu/v1/courseclass/{courseClassId}
UAT URL	https://studentws-uat.stanford.edu/v1/courseclass/{courseClassId}
Method	GET
Returns	200 & CourseClass XML
	400 & error XML: courseClassId does not look like termId-courseId or termId-subject-catalogNumber
	404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId or termId-subject-catalogNumber eg, 1026-103398 or 1026-CHEMENG-450

Get course XML

Description	Get course XML by Id
URL	https://studentws.stanford.edu/v1/courseclass/{courseClassId}/course
UAT URL	https://studentws-uat.stanford.edu/v1/courseclass/{courseClassId}/course
Method	GET
Returns	200 & Course XML
	400 & error XML: courseClassId does not look like termId-courseId or termId-subject-catalogNumber
	404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId or termId-subject-catalogNumber, e.g., 1026-103398 or 1026-CHEMENG-450

Get class XML by courseClassId and class offeringNumber

Description	Get class XML by courseClassId and class offeringNumber
URL	https://studentws.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}
UAT URL	https://studentws-uat.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}
Method	GET
Returns	200 & Class XML
	400 & error XML: courseClassId does not resemble termId-courseId, e.g., 1026-103398
	404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId, e.g., 1026-103398

Get class XML by class id

Description	Get class XML by Id
URL	https://studentws.stanford.edu/v1/class/{classId}
UAT URL	https://studentws-uat.stanford.edu/v1/class/{classId}
Method	GET
Returns	200 & Class XML
	400 & error XML: classId does not resemble termId-subject-catalogNumber, e.g., 1026-CHEMENG-450
	404 & error XML: classId is invalid.

classId should look like termId-subject-catalogNumber e.g., 1026-CHEMENG-450

Class search by termId and subject

Description	Search classes for given termId and subject. termId parameter is optional. If termId is not provided, the current termId is used for class search.
URL	https://studentws.stanford.edu/v1/class/search?termId=1074&subject=ENGR
UAT URL	https://studentws-uat.stanford.edu/v1/class/search?termId=1074&subject=ENGR
Method	GET
Query String	termId=1074&subject=ENGR
Returns	200 & classes XML
	400 & error XML: required parameter subject is missing
	404 & error XML: No class is found for given search criteria

Class search by termId and acadId

Description	Search classes for given termId and acadId. termId parameter is optional. If termId is not provided, the current termId is used for class search.
URL	https://studentws.stanford.edu/v1/class/search?termId=1074&acadId=GSB
UAT URL	https://studentws-uat.stanford.edu/v1/class/search?termId=1074&acadId=GSB
Method	GET
Query String	termId=1074&acadId=GSB
Returns	200 & classes XML
	400 & error XML: required parameter acadId is missing
	404 & error XML: No class is found for given search criteria

Get section XML

Description	Get section XML by courseClassId, class offeringNumber, and section classNumber
URL	https://studentws.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}/section/{classNumber}
UAT URL	https://studentws-uat.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}/section/{classNumber}
Method	GET
Returns	200 & section XML
	400 & error XML: courseClassId does not resemble termId-courseId eg, 1026-103398
	404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId, e.g., 1026-103398