shaarli / api-documentation Goto Github PK

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

As discussed in #3 we have 2 ways to handle parameters:

or

Optionally we can add URL rewriting for cleaner URL.

The first one requires a bit of work to handle parameters properly, while the second one makes URL rewriting more complex.

EDIT: parameter names are also debatable, but won't be used client side if we add URL rewriting.
EDIT BIS: I forgot the API version, but you get the idea.

Hello,

I would like to contribute to the documentation and add a code snippet of the Shaarli API usage with Android.

I have written everything here. I am just starting to learn Android and I know I had some trouble making this work, so I am confident other people will take advantage of this.

I am not sure of how and where you would like to put the snippet so I opened this issue.

As discussed in #2, we need a way to authenticate clients to Shaarli's API.

I'm in favor of using JWT:

• widely used, so there are client libraries in any language.
• pretty much easy to implement if you want to
• unique token for any request based on salted hash

@virtualtam has proposed to used an authentication process

When emitting several requests over an HTTP service that requires authentication, one usually:

• opens an HTTP session with a first request carrying the credentials,
• reuses this session to send further requests

Another possibility is OAuth in client_credentials mode. IMHO it's a bit too complex but it's not that hard:

• the client has an ID + secret
• get a temporary token from a refresh_token endpoint
• carry its token in every request

EDIT: actually OAuth without a database is a bad idea, because we need to store clients, authorization code and tokens, at least.

https://shaarli.github.io/api-documentation/ currently shows the documentation as proposed in #16, even though the Pull Request has not been merged.

#2 is not how I want to do it in the future – I tried a wiki edit but see a lengthy discussion while the according page remains blank.

I understand REST as

1. use HTTP verbs
2. use URIs like in DELETE /posts/Shsmbw or POST /posts/
3. use HTTP status codes and reason phrases as in http://stackoverflow.com/questions/942951/rest-api-error-return-good-practices/34324179#34324179

may I raise this question to be clarified explicitly? I touched it in shaarli/Shaarli#586 (comment)

• what are the deliverables of this project?
• what about acceptance tests?
• what are the quality-expectations (regarding the api server side implementation) in a coarse grained manner a la https://github.com/mro/ShaarliOS#design-goals
• what is the process for approving api changes (including experimental/stable/deprecated/purged state changes)

Currently, the title is required for POST and PUT link endpoints. It shouldn't, as we can do like in the UI, use the URL as a title.

So there is no required field, an empty request would make a note with its shorturl as a title.