Introduction

Welcome to umd.io, the open-source API for University of Maryland data. If you are building a University data-focused app, hack, or project, you’re in the right place. This site will walk you through basic API use and document all supported API calls.

Read more about the motivation and vision for the project in the blog post.

umd.io is a GETful API. It follows RESTful conventions, but for now, you can only get data – you can’t create, update, or destroy.

The API is in version 0. We are adding, changing, and breaking things all the time. Contact the team or (preferably) create an issue on github if something isn’t working the way you think it should.

We are actively looking for contributors! Tweet, email, or otherwise get in touch with us.

API Endpoint

http://api.umd.io/

Versioning

The current version is version 0.

When we release a new version of the API that isn’t backwards-compatible, we’ll update the version number. The old version will remain accessible, but we’ll deprecate and no longer support them after a reasonable amount of time. Even though ‘/v0/courses’ might be very different than ‘/v1/courses’, your app that uses v0 will still work.

Every request needs to specify the version number in the url. If you leave out the ‘/v0’ or ‘/v1’, or you’ll get an error.

The current version is live at:

http://api.umd.io/v0

Pagination

Endpoints that return a large amount of items are paginated to 30 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?per_page parameter.

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.


The possible rel values are:

Name Description
next Shows the URL of the immediate next page of results.
last Shows the URL of the last page of results.
first Shows the URL of the first page of results.
prev Shows the URL of the immediate previous page of results.

Example: http://api.umd.io/v0/courses?page=2&per_page=100








Link: <http://api.umd.io/v0/courses?page=2&per_page=100>; rel=”next”, <http://api.umd.io/v0/courses?page=1&per_page=100>; rel=”prev”

Expanding objects

Queries that return the ID of another object nested within the result can be expanded via the ?expand=<object> parameter. For example, the query http://api.umd.io/v0/courses/cmsc131 returns a “sections” key with an array of Section object ids. To expand these into their full objects, you can pass ?expand=sections to expand the section ids to their section objects.

Example expand query: http://api.umd.io/v0/courses/cmsc131?expand=sections

Currently, this only works on the Get courses endpoint.

Errors

200 - OK

Everything worked as expected. If you aren’t getting the result you expected, it might mean that the data you are trying to access doesn’t actually exist in the database.

400 - Bad Request

This means that the url in your request couldn’t possibly match anything in the api, probably because of a misspelling.

404 - Not Found

The requested url doesn’t exist. This happens when the url isn’t anything on our end, not even a badly formed request.

500 - Internal Server Error

Something went wrong on our end. We try not to send you this. If you get one, let us know, and send us all you can about the circumstances of your error.

Sample requests

http://api.umd.io/v0/courses/ENGL101 200: Works as expected

http://api.umd.io/v0/courses/ene10 400: ‘ene’ is only 3 letters and ‘10’ is only two digits, so there is no way this could be a proper request.

http://blargyblarg.umd.io 404: blargybarg isn’t on our server, so you won’t find it. If you misspell a word in a url, you might get this.

http://api.umd.io/v5/courses 404: Courses aren’t at version 5 yet. (We’re not even up to version 1!)

http://api.umd.io/courses 404: You need to specify a version number!

http://api.umd.io/v0/course 404: ‘course’ isn’t an endpoint; ‘courses’ is. Even little misspellings will get ya!

http://api.umd.io/v0/courses/ENGL115 404: There’s no course with that course_id.

Tips and Tricks

While you are exploring the api via the browser, the JSON Formatter extension will make the output readable.

Terms of Use

Don’t just skip these! By using the site and the API, you automatically agree to these Terms of Use.

umd.io is built by students for students - we aren’t the school, and we aren’t a corporation. We try to provide the best tool that we can, and we know that he better service we provide, the more students will rely on it, and the better everyone’s experience will be.

That being said, we can’t guarantee that the API will always work the way it is documented, the way it should, or even work at all! We’re offering the service to be helpful, and we are licensed so that you can use it for any kind of project - a small one for yourself or for class, or a for-profit business. Still, we make no warranties or guarantees of any kind, and you, by using the site and service, fully indemnify and hold harmless umd.io and everyone associated with it. You also agree to limit our liability as much as the law permits.

We don’t currently have any rate limits, but we might at some point, at will at that time update these terms. We reserve the right to limit your use or even shut you out entirely. We would likely only do this to protect the service, such as if you made so many calls to the API that it couldn’t handle it.

We don’t collect any personally identifiable information, but the IP address of whatever application is calling the API will probably end up in log files. We don’t share these with anyone, and they would be tough for someone to steal, but again, we don’t guarantee anything.

We’re based in Prince George’s County, Maryland, and if it came to it, you agree that any legal dispute would be settled in those courts.

These terms went into effect on 5/5/2015, when they were written. If they are updated, we’ll post the notice here, and the changes will go into effect 15 days after they are posted here.