Skip to content

Instantly share code, notes, and snippets.

@ozh ozh/api.yourls.org.md
Last active Dec 26, 2015

Embed
What would you like to do?
YOURLS API notes

api.yourls.org Design principles - document in progress

Versioning

  • 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)

Output

  • 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 https://blog.apigee.com/detail/restful_api_design_tips_for_handling_exceptional_behavior/)
  • 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

Access

Structure:

/scope/noun/version/?parameters_if_need_be

Minimal documentation

Each API method should include its own minimal documentation:

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

API

YOURLS Core:

  • /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 https://gist.github.com/ozh/5518761 when the cron feature is running. (Also POST that on install/update)

Misc services:

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

Documentation

  • /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.