Discussion items


  • REST API General Guidelines
  • very good proposal, discussion about small details around different edges
  • related to paging

    • might be worth returning total expected count

    • it is optional

  • returning errors
    • if we have an option to return specific error, specific context in json format (Eg this is my app 500 error, not apache), we will. Otherwise standard html error
    • return everything we know about given error
  • bad sql statement - how will error msg look like?

    • perhaps add additional container for this kind of errors
  • query succeeded, but no results - how will the response look like?
    • not through 204
  • finding what is available / what functions the server can handle
    • wadl (Web Application Description Language)
    • want to move to sth self describing instead of static API page
  • L3 users: will have a choice of direct queries, or RESTful API
    • what about users connecting from outside?
    • Need to understand what public services are visible from outside of LSST servers (question for Kian-Tat Lim)
    • e.g., is everything going through RESTful API (and no direct queries) if connections are coming from outside world?
    • forcing them to go through RESTful API would provide additional level of safety
    • Gregory will open a story to capture this

python vs java

  • Trey mildly concerned about using python in server side
    • for performance reasons
  • Thread per request?
    • if API is truly RESTful, not much shared information on the server, so can have many servers, or multiple python back ends for apache
  • universal for both python and java: web load balancer (like nginx)
  • java could be more efficient, depends how it is written
  • easier to connect to pipelines code from python
  • rewrite from python to java shouldn't be too hard




  1. Since I won't be able to make the meeting, I'll say that I generally agree with Brian's guidelines, except that I think there should be API URLs that return resources (images, catalogs) in specific formats (FITS files, VOTables) directly, without any JSON wrapping.

    1. I don't think I responded to this. I agree. In general, those requests will likely be fulfilled with a different Accept header, such as Accept: image/fits. The recommendations are officially for Accept: application/json request types, and don't apply to other types.

      If I'm not mistaken, I believe the default format will be json as well, so any requests which send Accept: */* should be equivalent to Accept: application/json by default.



  2. I have always expected that advanced end users or utilities acting for them will be able to connect directly to Qserv or other DAC databases using a database client, hence the desire to provide a MySQL or other common API interface.  Given such an interface, I see no reason to restrict it to connections originating in the L3 resources, provided that suitable authentication, authorization, and resource management can be provided.

    If we were to limit users to using a REST API that we define, then we can take many more liberties with Qserv's interface (though not necessarily SQL support).  I see this as a requirements question.