search

stacks-network / stacks

Overview of Bitcoin's Stacks layer.
https://www.stacks.co/
2.03k stars 243 forks source link

API stability and versioning #381

Closed vsund closed 6 years ago

vsund commented 6 years ago

After consolidating https://github.com/blockstack/blockstack/issues/376 we should try to define some kind of measurement for API stability and process for versioning.

For example if I'd like to use only the naming feature today and my app is completely external (e.g. as OpenBazaar) there are no information on how to or guaranteed-stable APIs for this (or if it is, it's not communicated somewhere publicly present).

I'd like to suggest to stabilize all exposed APIs in a unified way (maybe at a future version of https://github.com/blockstack/blockstack.org/issues/474?). Really important if people start building on top. Besides there are currently many many working places but also new things get started (mostly before the current ones are finished / stabilized ;))

Also really important to keep in mind: When APIs are somewhat popular, it's hard / costly to make bigger changes on interfaces. As an extreme example: If you'd like to replace TCP by another protocol, you'd have no other chance than using the same interface as TCP does.

(I opened this issue here at blockstack/blockstack because it's not really an issue with Core itself but a more general one.)

vsund commented 6 years ago

I think it would be useful to group API endpoints into their purposes (API endpoint means REST endpoints as well as exposed methods by a library). We then could start releasing (and versioning) them along with documentation and how-to.

For example we have blockstack.js and go-blockstack, but they have fundamentally different purposes. blockstack.js is for writing web apps for consumers but go-blockstack is a high-performant (read-only?) library powering things like blockstack-explorer. So developers might see a lot of libraries, but won't be able to tell easily what kind of library it is. Especially for work-in-progress ones: what can the library already do?

We could solve this with hints in the corresponding READMEs stating that

This library is capable of x, y and z.

but saying that

This library implements Blockstack client spec v1.2.3 (with link).

would be way more convenient and consistent. Besides this would empower developers to easily comprehend implemented features and measure their own requirements (for implementing libraries in other languages).

cc @jackzampolin

jackzampolin commented 6 years ago

Closing in favor of https://github.com/blockstack/blockstack.js/issues/235

vsund commented 6 years ago

This was meant as a slightly bigger issue, probably even including https://github.com/blockstack/blockstack.js/issues/235.

https://github.com/blockstack/blockstack.js/issues/235 is about finalizing the blockstack.js API and publishing it. This is more about Developers implementing a new library and our messaging / process around that (and also about the other APIs that are exposed, e.g. Core endpoints, Gaia Hub endpoints; these would be way more easy to comprehend it there would be a unified way to browsing them).

For example how we'd like to hint several "types of libraries" (e.g. server lib for high performance, app lib for consumer apps, etc).