HackageDB/2.0/URIs

    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.

This document was created on May 30, 2010. As of August 2010, this isn't a complete (or entirely accurate) list, and should be updated.

URIs

Top-level

  • /
    • GET: site introduction page

User accounts

  • /users/
    • GET: list of users
    • POST: Add user, admin only. Might also be allowed as free registration.
  • /users/admins/
    • GET: list of admins and contact info
    • POST: add admin (may not be provided by web interface for security reasons)
  • /users/admins/<username>
    • DELETE: delete admin (likewise)
  • /user/<username>
    • GET: return basic user info, user actions
    • 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 /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)
    • 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 make a placeholder package (for a mirror). 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 (for a mirror).
    • 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. Tarball seems like the best approach, although .haddock files might be appropriate.
    • DELETE: delete new documentation
  • /package/<package>/src/<srctree>
    • GET: reading straight from source tarball, if this isn't too slow
  • /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/. To replace recent.html and recent.rss

Distributions

  • /distros/
    • GET: a list of distributions with their own Haskell lib packaging systems (currently Arch, Debian)
    • POST: create new distribution. Field name "distro". Very infrequently accessed I suspect.
  • /distro/<distro>
    • GET: list of releases of this distribution
    • POST: create a new release. Field name "release"
    • DELETE: removes this distribution
  • /distro/<distro>/<release>. <release> can be "default" if the distribution does not distinguish releases.
    • GET: list of packages in a given release, potentially paginated. Also supports CSV format (append ".csv): Package name, Version, URL.
    • PUT: bulk-upload of packages in CSV format. Wipes out any previous entries for this Distribution.
    • DELETE: removes this release
  • /distro/<distro>/<release>/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.