shaarli/api-documentation

General discussion

ArthurHoaro opened this issue · 11 comments

ArthurHoaro commented

There are a few things that's need to be defined.

API services

It should describe every services in details. See the first example https://github.com/shaarli/api-documentation/blob/master/api-documentation.md (feel free to propose a better format if you know one).
Different services should be discussed in different issues/PR.

Authentication

Which method are we using? Could be a good idea to provide a few client usage example like done in shaarli/Shaarli#586

Implementation choices

There are a lot of framework and libs to deal with REST API out there. Should we use one of them?

ping @mro @toneiv @pikzen @dimtion

mro commented

API services

I'd love to start with

  1. design goals (coarse grained like https://github.com/mro/ShaarliOS#design-goals)
  2. high level requirements like security, discoverability, versioning,
  3. a process (and timeframes) how to have the community agree on marking calls experimental/stable/deprecated,
  4. a working test environment (and ci / travis) that serves as a mold for the api calls themselves.

I wouldn't bother to write prose that's always out of-sync with what's

  • current API,
  • running API of a given instance.

Authentication

see 2. above. What are the requirements? Federation? Standards compliance? (e.g. OAuth, OpenID (Connect?), HTTP Digest?)

Implementation choices

KISS, so I'd say no 3rd party code.

nodiscc commented

Implementation choices

Ideally less than 100-200 SLOC.

  • 👍1
  • 🎉1
ArthurHoaro commented

Ideally less than 100-200 SLOC.

If you include services in those, it might be a bit ambitious.

ArthurHoaro commented

does something like this make sense? http://www.phpspec.net/en/stable/manual/getting-started.html

It looks like unit tests with a bit of additional magic in it. I'd say we stick our good ol' PHPUnit.

nodiscc commented

I was thinking about adding GET stats (returns statistics such as number of public/private/all links, number of tags, some config values such as the list of enabled plugins, timezone, maybe more?). I'll try to do it soon, please tell if you have remarks about this.

Does it make sense to add a GET export (returns HTML exports of the shaares)? It would be nice to have a clean way to access those. Or should the client implement its own JSON -> Netscape HTML conversion?

virtualtam commented

returns statistics such as number of public/private/all links, number of tags, some config values such as the list of enabled plugins, timezone

This could prove handy, yet we need to ensure no sensitive server information or configuration entries can be disclosed this way.

Does it make sense to add a GET export (returns HTML exports of the shaares)?

The REST API should by definition return JSON-formatted data, that the client should then parse for further processing (e.g. updating a database, adding custom fields, etc.)

Exporting as a Netscape bookmark file to import it somewhere else could turn out to be quite a hazardous operation, depending on the external parser. I'm not sure it's worth (sensible?) making it available through a programmatic-friendly interface.
By the way, most requests we've received through GH issues were going towards interfacing Shaarli with other software and databases.

  • 👍1
ArthurHoaro commented

About the documentation format, I suggest that we use API Blueprint which is an API documentation specification built on top of markdown. There are a few tools like aglio which renders it in HTML nicely.

ArthurHoaro commented

It was a bit chaotic, but I finally got it working automatically: http://shaarli.github.io/api-documentation/

I had to merge everything, but obviously you can still give your feedback on the API doc.

nodiscc commented

Thank you! Very good result, and interesting build config. 👍👍👍

  • What would Shaarli return for created (Link) when privacy.hide_timestamps is set to true?
    • Empty value? Don't return created at all?
    • Would it be useful to have /info return the value of privacy.hide_timestamps (Settings)?
  • Is (Link) id different from the link's smallhash?
ArthurHoaro commented

Timestamps are hidden while logged out whereas the API is authenticated only. It wouldn't cost much to add it to /info though, if anyone find it useful.

Link IDs are "linkdate" for now (e.g. 20160606_101010), but I think there is an open issue in Shaarli to convert them to proper unique ID. Smallhash isn't used in the API.

EDIT: Actually, shaarli/Shaarli#351 is set for v0.8.0. I'll probably work on it after the API, so linkdates ID may not last.