shaarli / api-documentation Goto Github PK
View Code? Open in Web Editor NEWShaarli's REST API specification and documentation
Home Page: http://shaarli.github.io/api-documentation/
Shaarli's REST API specification and documentation
Home Page: http://shaarli.github.io/api-documentation/
I understand REST as
DELETE /posts/Shsmbw
or POST /posts/
#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.
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?
may I raise this question to be clarified explicitly? I touched it in shaarli/Shaarli#586 (comment)
https://shaarli.github.io/api-documentation/ currently shows the documentation as proposed in #16, even though the Pull Request has not been merged.
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 #3 we have 2 ways to handle parameters:
Method | Endpoint |
---|---|
DELETE | ?do=api&q=/links/Shsmbw |
POST | ?do=api&q=/links |
GET | ?do=api&q=/links&limit=20 |
or
Method | Endpoint |
---|---|
DELETE | ?do=api&request=links¶m=Shsmbw |
POST | ?do=api&request=links |
GET | ?do=api&request=links&limit=20 |
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.
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.
As discussed in #2, we need a way to authenticate clients to Shaarli's API.
I'm in favor of using JWT:
@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:
refresh_token
endpointEDIT: actually OAuth without a database is a bad idea, because we need to store clients, authorization code and tokens, at least.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.