Skip to content

Instantly share code, notes, and snippets.

@ozh ozh/

Last active Dec 26, 2015
What would you like to do?
YOURLS API notes Design principles - document in progress


  • Never release an API without a version.
  • Make the version mandatory (or 404) (except for /doc - see below)
  • Version format should be \d+\.\d+ (eg 1.0, 1.1, 13.37)


  • Serve JSON or plain text as text/plain; charset=utf-8
  • Pretty print JSON (json_encode($data, JSON_PRETTY_PRINT);)
  • Status codes: 200 OK / 404 Not Found / 400 Bad Request
  • support JSONP (?jsonp=blah)
  • Implement ?suppress_response_codes=true to override the status code (see
  • Implement ?format=html for easier browser testing ? (useless if pretty print?)
  • JSON object attributes in camelCase to stick with YOURLS core API (eg statusCode)

Todo: Cache all the things




Minimal documentation

Each API method should include its own minimal documentation:

  • short description
  • parameters if any
  • pastable example (curl command or direct link)



  • /core/version/1.0/ : latest stable tag + POST stuff
  • /core/credits/1.0/ : list of contributors. By tag?

The version method should accept POST stuff from when the cron feature is running. (Also POST that on install/update)

Misc services:

  • /services/md5/1.0/ (deprecated?)
  • /services/cookie-key/1.0/


  • /doc/ should output a list of all possible routes and usage

Documentation will not be "an API": human readable output only, and subject to change format without notice

Future stuff

Possible future stuff

Plugins ?

  • /plugins/.../ ?

Themes ?

  • /themes/.../ ?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.