Adding a Web Service

Steps to add a new web service. This is working through a specific example.

  1. Add a new route to _wsvc/conf/wsvc.routes:

    GET  /api/v2/course/:termidFrom-:termidTo/:userid/offerings
    oat.wsvc.controllers.CourseCtrl.offeringsByInstructor(termidFrom:TermId, termidTo:TermId, userid:Userid)

  2. Add the corresponding function(offeringsByInstructor) to the relevant controller (CourseCtrl). Note that there may be identically named controller classes in both _wapp and _wsvc. Get the right one!

  3. Register the call in the controller’s companion object. This is where required permissions are set and the source of brief documentation that appears at https://oat.uwaterloo.ca/api/v2/.

    Don’t do too much here. The controllers should essentially take care of security/permissions and logging the action. The rest should be done in another layer. That layer is typically injected as an implicit into the controller class. For the offeringsByInstructor example, it’s the webSvc: CourseWS in the controller’s parameters.

  4. Go to the web service (CourseWS) and add the function header to the trait. The trait, of course, allows us to substitute a different implementation for testing or other purposes. Unfortunately, that’s rarely been done.

  5. Add the corresponding function to the class implementing the trait. Here, at last, is where the real work gets done. Lots of web services are just returning information, in which case this function just makes a call to the database. In others, it may be updating the database in which case validation and some other work may be appropriate/necessary.

    In a very few cases we have a “business logic” layer so that the web service is basically just interacting with the database. I’m not sure it’s worth it.

    In some cases the SQL is right in the implementing function. In other cases it just calls a stored procedure so that the bulk of the SQL is defined in the database. There is no hard-and-fast rule for doing one vs. the other. One criteria is whether the SQL can be reused. In that case, put it in the database. In the current example, offeringsByInstructor reused a stored procedure that was previously used by two other web services.

  6. Test the web service in your browser.

  7. Make sure the documentation shows up at https://oat.uwaterloo.ca/api/v2/. That documentation is based on the call registered in the controller. If the route has something funky in it, you may need to make some adjustments in the oat.server.auth.RouteEntry class.

  8. Update the AboutView and the relevant gitlab issue.

  9. In the OAT app’s Admin -> Maintain Users page, give the relevant developers permission to access the web service in their browser.