YOURLS API notes

api.yourls.org.md

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

• https as a primary protocol, but support http
• GET to read stuff
• POST to write stuff: collect anonymous stats, see https://gist.github.com/ozh/5518761

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

• /stats/stuff/1.0/ where stuff is from https://gist.github.com/ozh/5518761

Possible future stuff

Plugins ?

• /plugins/.../ ?

Themes ?

• /themes/.../ ?