Comments (11)
Sounds great, I'd love to see Observatorium formalize its development process more.
To add some historical context, the project already published a few releases in semver format up to 0.1.2. Even though the last release was over a year ago and lots of things have changed, we could probably start our next release at 0.2.0, since there are no guarantees of API compatibility for any release below 1.0.0.
from api.
Versioning the spec in the same way as the API itself would be nice
Hmm I tend to disagree here. The HTTP API is a contract and the version of that contract should only change when the contract changes. By contrast, the version of the binary can change whenever new features are added or removed. E.g. we remove OPA support from the binary, causing the need for a new major release, but the HTTP API stays exactly the same, so this version stays the same. This is also incidentally how Kube does its versioning: all of the APIs (e.g. apps/v1) are versioned independently from Kube releases (e.g. v1.23.0).
from api.
We have an openapi spec added for metrics and rules/raw - I wonder if it makes sense to expand to the other signals and integrate the api versioning with the specs? Not sure what would be the best practice
from api.
Adding log support in openapi spec is planned in #294. Versioning the spec in the same way as the API itself would be nice as people can generate tooling according to versions! :)
from api.
That makes sense and is a better approach than what I suggested!
We haven't been maintaining a versioned spec either so that would also be a task.
from api.
Yes. We also need to think carefully about ensuring that the paths that the HTTP API exposes actually conform to the version of the API contract, e.g. the Rules API is currently set to 0.0.2 [0] but most of our HTTP paths say x/v1/y, whereas here it should probably be x/v0/y.
[0] https://github.com/observatorium/api/blob/main/rules/spec.yaml#L4
from api.
At the risk of going slightly off topic, what are the plans for the legacy metrics endpoints going forward? Does it need to be maintained?
It would be great to have some sort of roadmap for the project and its intentions to get to a stable release going forward.
from api.
@PhilipGough I guess since we don't really have a stable version yet, we could simply deprecate it and eventually remove it after couple of minor releases
from api.
I think that by calling it legacy it is already effectively deprecated, no? I would be in favor of dropping it from main and cutting a new release soon.
from api.
AFAIK no one depends on it, I'm totally fine with dropping it straight away; just if we wanted to be more cautious and do it over the course of couple releases, but it seems it's not necessary.
from api.
if there are no dependencies to the current legacy endpoints I'd be in favor to dropping it straight away as well :) +1
from api.
Related Issues (20)
- Update to go 1.17 HOT 1
- tenant logout handler HOT 2
- Expose flag traces.read.endpoint in jsonnet HOT 2
- Trace Read tenancy architecture and implementation HOT 1
- What Claim Name in openid tokens is used for representing groups? HOT 3
- Add OpenAPI spec for logs HOT 1
- HTTP handler monitoring middleware isn't the topmost in the middleware stack HOT 2
- Update oapi spec for better API documentation
- Consider adopting the Prometheus JSON format for error responses HOT 2
- oidcConfig: is ClientSecret used? HOT 2
- OIDC authenticator skips identity check if no username or group claim are present HOT 5
- Support Certificate Revocation Lists for mTLS Authentication
- Rules API spec has non-optional fields
- Optional endpoints for beta deployments HOT 3
- Logs Gateway corrupts query HOT 2
- Breaking change in rate limiting endpoint matching
- Make e2e tests arm64 friendly
- support reading configs from environment variables HOT 3
- Intorducing testify library for unit tests
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from api.