Consider changing formatting of query parameters

[arkon]

The Web API parameters seem awfully overcomplicated when you could probably just make use of JSON to pass in parameters that are more easily readable like "breadth": "1, 2", "level": "<= 200", etc.

[qasim]

Thanks for the feedback, we thought the same.

Do you mean that we should have one parameter we take in, say "query", which gets passed a JSON object like query={ "breadth": "1, 2", "level": "<= 200" } or is there some better way to pass JSON objects through GET requests?

[arkon]

You might have to switch to a POST request to use JSON, actually. It's really up to the API design.

I feel like @elliottsj might be able to offer some more insight into this.

[elliottsj]

From what I understand, the API uses GET query parameters, and you can use those operators (,, /, -, etc.) in the query parameters to filter search results.

e.g.

GET http://localhost/courses?prerequisites=CSC148&course_level=100/200

which would return 100-level and 200-level courses that require CSC148.

I think this is the right approach for filtering results; though my only critisism is that it may be better to use the actual words "AND", "OR", and the operators >=, <=. It sacrifices some readability of the URL string, but it's more meaningful when you're building a query programmatically.

---

However this API seems more suited to be a 'search' API than just a way to filter results. Like GitHub for example:

• GET https://api.github.com/repositories: dumb listing of repos; no filtering
• GET https://api.github.com/search/repositories?q=tetris+language:assembly&sort=stars&order=desc: allows keyword search, filtering by qualifiers

Like GitHub's search syntax, having just a single q=... parameter for the query means you can make queries like "prerequisites:'CSC108H1' OR course_level:100", which wasn't really possible using separate query parameters.

[qasim]

After quite some research on asking around which may be a better option, we've come up with the following:

• GET courses/show/:id
  • Gets the course document at the specified id
  • eg. CSC108H1F20149
• GET courses/search?q=<QUERY>
  • Performs a fuzzy search on courses based on the query presented
  • eg. q=natural language computing
• GET courses/filter?q=<QUERY>
  • Filters courses based on a provided query in a format
  • eg. q=breadth:'1' AND level:'<=200' OR code:'CSC'

This seems the most elegant way to accomplish the tasks we set out to solve with the courses API.