HackageDB/2.0/URIs

Version 3 (modified by mgruen, 3 years ago)

fix bad phrasing

    1. URIs
      1. Top-level
      2. User accounts
      3. Packages
      4. Build reports
      5. Logs
      6. Distributions
    2. Content types
    3. User groups
    4. HTTP methods

Rough draft of new URIs, mostly excluding static pages.  REST and  ROA may explain some of the reasoning.

URIs

Top-level

  • /
    • GET: site introduction page

User accounts

  • /users/
    • GET: list of users
  • /users/admins/
    • GET: list of admins and contact info
  • /users/admins/<username>
    • PUT: add admin (may not be provided by web interface for security reasons)
    • DELETE: delete admin (likewise)
  • /user/<username>
    • GET: return basic user info, perhaps packages uploaded
    • PUT: Add user, admin only. If free registration were allowed, it might be as a POST to /users/
    • DELETE: Delete user
  • /user/<username>/password
    • PUT: change password. Admins can change anyone's password, but everyone else can only change their own.

Packages

  • /packages/
    • GET: cached big package list
    • POST: to replace current /packages/upload, add new package to collection of packages
  • /packages/index.tar.gz
    • GET: to replace current /packages/archive/00-index.tar.gz
  • /package/<package>
    • GET: return package description page, distilling .cabal data into as helpful a form as possible. <package> is a valid package identifier, e.g. utf8-string-0.3.5 or GLUT (current version)
    • PUT: this might behave like POST to /packages/, or more likely it would create a placeholder package to upload metadata and tarball later
    • DELETE: admin only, zap package or package-version from face of the earth after many confirmation dialogs (and maybe protected by a backup system)
  • /package/<package>/<package>.cabal
    • GET: return cabal metadata for package
    • PUT: replace .cabal file for existing package or add it to placeholder package. Subresources of this one might allow post-upload editing by the package maintainer.
    • DELETE: delete .cabal file. This might not be so useful.
  • /package/<package>/<package>.tar.gz
    • GET: retrieve tarball for installation
    • PUT: replace tarball for existing package or add it to placeholder package.
    • DELETE: delete tarball.
  • /package/<package>/doc/<doctree>
    • GET: get documentation, potentially reading straight from tarball, if this isn't too slow
    • PUT: upload new documentation tarball
    • DELETE: delete new documentation
  • /package/<package>/maintainers
    • Maintainers can be added (upon upload, by admins and existing maintainers) and removed (by admins) using an interface like /users/admins/

Build reports

  • /package/<package>/reports/
    • GET: list of report IDs for a package with links to each
    • POST: send in a report and get an ID
  • /package/<package>/reports/<id>/
    • GET: format report information
    • DELETE: by package maintainer or admin
  • /package/<package>/reports/<id>/log
    • GET: compilation log of failed build, can limit access only to maintainer if privacy is a concern
    • DELETE: by package maintainer or admin

Logs

  • /log/packages/
    • GET: unless the requested format is text/plain, redirect to /log/packages/recent/
  • /log/packages/<page>/
    • GET: paginated results for the upload log. /recent/ is an alias for /1/.

Distributions

  • /distros/
    • GET: a list of distributions with their own Haskell lib packaging systems (currently Arch, Debian)
  • /distro/<distro>
    • GET: list of packages in a given distribution, potentially paginated
    • PUT: create new distribution. Very infrequently accessed I suspect.
    • DELETE: likewise remove
  • /distro/<distro>/package/<package>
    • GET: information about a given package, particularly the URL.
    • PUT: indicate a newly uploaded package. This will be requested by the distribution itself
    • DELETE: package is no longer available.
  • /distro/<distro>/maintainers
    • Maintainers can be added (by admins and existing maintainers) and removed (by admins) using an interface like /users/admins/

Content types

Except for the cabal and tarball files, all of the above URIs will serve an HTML content-type, and POST requests will be submitted either as multipart/form-data or application/x-www-form-urlencoded. To use a different format, for example JSON, either send an Accept: application/json header or indicate the format in the URL. This may be a simple ?format=json query, or a .json extension to any URL (see  Reddit's API for explanation).

User groups

I'm leaning towards having a relatively decentralized set of user groups. So you can view a given user group for a given resource at <resource>/<groupname>, and PUT or DELETE at <resource>/<groupname>/<username> so long as the user exists, deleting only if already in the group.

HTTP methods

Browsers will have trouble dealing with PUTs and DELETEs if they're not HTML 5-capable (no way of knowing this) or can't do Ajax (JavaScript? might be disabled). To get around this, send _method=PUT or _method=DELETE as part of a POST query, and the web server will munge the request into thinking you sent a PUT/DELETE. This shouldn't introduce any significant HTTP-violating issues, since it will only activate on POSTs, and I think it's how Rails does it.