Project goals

[mro]

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)

[mro]

also touched in #1 (comment)

[nodiscc]

shaarli/Shaarli#586 (comment)

What would you consider goals and non-goals?

the first stable version should be able to retrieve, search, post, edit and delete links

---

what about acceptance tests?

Can you clarify?

what are the quality-expectations

Reliability and secure operation should come first. The API mechanisms will leverage existing security features (such as access control for private links, IP banning, etc.). An authentication method needs to be defined, it should not try to protect the client against passive sniffing (that's what TLS is for), but can reasonably protect against token reuse/session replays (eg. by expiring the token).

Functionality, usability: retrieve, search, post, edit and delete links are a basic first step. These features will be accessed through GET and POST HTTP methods. Other features can be implemented later, such as: get the number of public/private/all links, export HTML bookmarks, get the list of tags, etc.

Reliability, changeability: Once an API endpoint has been defined and implemented in Shaarli, it should not be changed in the future in a way that it causes clients to break. Non-backwards compatible changes may be proposed for a future version of the API.

Portability: any client written in any language should be able to work with the API, as long as it has the capability to use above mentioned HTTP methods, and parse resulting JSON data.

what is the process for approving api changes

Submit a Pull Request to this repository while minding the above points, discuss it/amend it with other contributors until it reaches a reasonable consensus.

Does it answer most of your questions? Only speaking for myself, @ArthurHoaro @virtualtam get the final word.

[mro]

what about acceptance tests?

Can you clarify?

I mentioned before, that I would recommend specifying the API through mandatory tests that have to be passed. I'm not interested in documentation. But I'm interested in mandatory, reliable, enforcable, machine executable criteria. Often called acceptance tests.

Is this the goal of this endeavour? If not, I fear this here is a waste of time.

[mro]

what is the process for approving api changes

Submit a Pull Request

I recommend a defined time-frame until things change. E.g. require a deprecation period of 12 months.

[nodiscc]

I'm not interested in documentation. But I'm interested in mandatory, reliable, enforcable, machine executable criteria. Often called acceptance tests.

The API should be defined in the documentation first (other client developers will be interested in the doc), and yes, there should be a test suite (eg. a reference client, and verify that server responses match an expected behaviour, defined in the doc :) ). Preferably not a 1000-line bash script, there are tools more suited for this task (python requests and simplejson come to mind).

I recommend a defined time-frame until things change.

Once defined the API should not be changed (except minor, non-breaking changes). Building another, separate version of the API is still possible, and yes, there should be a reasonable period before phasing out a deprecated version of the API.

[mro]

The API should be defined in the documentation first

ok, expect me back when there are tests emerging.

[mro]

any news about tests meanwhile?