[Proposal] alertmanager/api: Introduce OpenAPI generated API v2

1,063 views
Skip to first unread message

Max Leonard Inden

unread,
Apr 30, 2018, 4:31:18 PM4/30/18
to prometheus-developers
Hi Prometheus developers,


I would like to propose a new fully generated Alertmanager API (v2). You
can find a proof of concept implementation with the OpenAPI project [1]
in PR #1352 [2].


# Why change API v1

The current Alertmanager API is undocumented and written by hand. This
is both error prone as well as difficult for other Projects in the
Prometheus ecosystem to integrate with.


# Benefits of a generated API

- The API server code can be fully generated with the exception of the
http handler logic itself.

- Clients using the Alertmanager API can be generated in all major
languages (Go, Java, JS, Python, Ruby, Haskell, *elm* [4] ...)

- Strict contract (OpenAPI spec) between server and clients.

- Instant feedback on frontend-breaking changes, due to strictly
typed generated frontend client.

- API documentation can be fully generated (See generated Alertmanager
API v2 online Documentation UI [5])


# Drawbacks of a generated API

- Dependency on e.g. open api ecosystem including go-swagger stack [3]


What are your thoughts on this? While I would like to redirect any
implementation specific discussions to the proof of concept PR #1352
[2], I would love to hear general feedback here.


Max




[1] https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
[2] https://github.com/prometheus/alertmanager/pull/1352
[3] https://github.com/go-swagger/go-swagger/
[4] https://github.com/ahultgren/swagger-elm
[5]
http://petstore.swagger.io/?url=https://raw.githubusercontent.com/mxinden/alertmanager/apiv2/api/v2/openapi.yaml

signature.asc

Brian Brazil

unread,
Apr 30, 2018, 5:40:51 PM4/30/18
to Max Leonard Inden, prometheus-developers
What's your plan for alert ingestion?

If we're going to move to something new, I see no need to keep any other part of our undocumented API.

Brian


--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com.
For more options, visit https://groups.google.com/d/optout.



--

Krasi Georgiev

unread,
May 1, 2018, 2:49:45 AM5/1/18
to Prometheus Developers
I am a big fan of swagger as well.
Last time I used it there was a point where we needed some additional feature or it had some limitation, I can't remember exactly, but should bare in mind that  using swagger is also a lock-in to what it actually supports.

There is another approach for swagger spec auto generation from an existing code using  annotations. This way we can benefit from auto generated docs without the swagger lock-in.

Here is an example of annotated code
https://github.com/go-swagger/go-swagger/tree/master/fixtures/goparsing/petstore

OTOH  this approach requires more manual work and is more error prone than the full auto generation.

Max Leonard Inden

unread,
May 1, 2018, 9:28:38 AM5/1/18
to prometheus...@googlegroups.com
> What's your plan for alert ingestion?

You are talking about `api.legacyAddAlerts` [1] or `api.addAlerts` [2]?
I would see the former as API v0 and the latter as API v1. I would
suggest deprecating both within the v1 deprecation period (see below).

> If we're going to move to something new, I see no need to keep any other part of our undocumented API.

I would suggest maintaining v1 and v2 for a transitioning period and
eventually deprecate v1 (and v0) in favour of v2.


> There is another approach for swagger spec auto generation from an existing code using annotations. This way we can benefit from auto generated docs without the swagger lock-in.
> https://goswagger.io/generate/spec.html

I have been trying out both "go code + annotations -> openapi spec" as
well as "openapi spec -> go code". I have quickly hit the limits of what
can be specified via the goswagger annotations feature. Thereby I have
focused on the latter process ("openapi spec -> go code") in my proof of
concept.


Additional general benefit that came to my mind is basic generated user
input validation logic.


[1] https://github.com/prometheus/alertmanager/blob/master/api/api.go#L137
[2] https://github.com/prometheus/alertmanager/blob/master/api/api.go#L147
> <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/mxinden/alertmanager/apiv2/api/v2/openapi.yaml>
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Prometheus Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to prometheus-devel...@googlegroups.com
> <mailto:prometheus-devel...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com
> <https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com?utm_medium=email&utm_source=footer>.
signature.asc

Krasimir Georgiev

unread,
May 1, 2018, 9:46:28 AM5/1/18
to Max Leonard Inden, prometheus...@googlegroups.com



Krasi Georgiev



There is another approach for swagger spec auto generation from an existing code using annotations. This way we can benefit from auto generated docs without the swagger lock-in.

I have been trying out both "go code + annotations -> openapi spec" as
well as "openapi spec -> go code". I have quickly hit the limits of what
can be specified via the goswagger annotations feature. Thereby I have
focused on the latter process ("openapi spec -> go code") in my proof of
concept.


"openapi spec -> go code" approach would be ideal and a great time saver so if you haven't hit any limitations in your POC than that would be the way to go.


Additional general benefit that came to my mind is basic generated user
input validation logic.


Yep that is a really great feature and really useful.

Another one is that you can quickly test the API directly in the browser with some pre-populated examples. No curl , no postman needed :)

Brian Brazil

unread,
May 1, 2018, 10:09:33 AM5/1/18
to Max Leonard Inden, Prometheus Developers
On 1 May 2018 at 14:28, Max Leonard Inden <ind...@gmail.com> wrote:
> What's your plan for alert ingestion?

You are talking about `api.legacyAddAlerts` [1] or `api.addAlerts` [2]?
I would see the former as API v0 and the latter as API v1. I would
suggest deprecating both within the v1 deprecation period (see below).

> If we're going to move to something new, I see no need to keep any other part of our undocumented API.

I would suggest maintaining v1 and v2 for a transitioning period and
eventually deprecate v1 (and v0) in favour of v2.

We have to keep Prometheus 2.0.0 working until at least there's a 3.0.0 - which is not going to be anytime soon.
 


> There is another approach for swagger spec auto generation from an existing code using  annotations. This way we can benefit from auto generated docs without the swagger lock-in.
> https://goswagger.io/generate/spec.html

I have been trying out both "go code + annotations -> openapi spec" as
well as "openapi spec -> go code". I have quickly hit the limits of what
can be specified via the goswagger annotations feature. Thereby I have
focused on the latter process ("openapi spec -> go code") in my proof of
concept.


Additional general benefit that came to my mind is basic generated user
input validation logic.


[1] https://github.com/prometheus/alertmanager/blob/master/api/api.go#L137
[2] https://github.com/prometheus/alertmanager/blob/master/api/api.go#L147


How would all this work for something like our existing v1 Prometheus APIs? Realistically they're never going away, so I'd prefer not to have to maintain two APIs indefinitely. 

Brian 

> To post to this group, send email to
--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/f6ea9174-8145-75f5-fa5c-f07a52e74eb5%40gmail.com.

For more options, visit https://groups.google.com/d/optout.



--

Stuart Nelson

unread,
May 2, 2018, 5:41:10 PM5/2/18
to Brian Brazil, Max Leonard Inden, Prometheus Developers
I still have to look at the code, but I will say that generating and using an API client based on an schema/api spec (my experience was with a go backend + protobuf definition with an elm frontend) was a real pleasure.

Is the legacy alert ingestion endpoint for a very old version of prometheus? If it's pre prometheus v1, I would be in favor of removing it.

A question: Do we want to deprecate the v1 api, or are we ok with just formalizing it with an openapi spec?

stuart

> To post to this group, send email to
--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-devel...@googlegroups.com.
To post to this group, send email to prometheus...@googlegroups.com.



--

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-devel...@googlegroups.com.
To post to this group, send email to prometheus...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLpXM3s8fk0wo-21C6NXEaeGKJR8ZBUkRfGWfA8%3DXdBiPg%40mail.gmail.com.

Brian Brazil

unread,
May 3, 2018, 2:18:45 AM5/3/18
to Stuart Nelson, Max Leonard Inden, Prometheus Developers
On 2 May 2018 at 22:40, Stuart Nelson <stuart...@gmail.com> wrote:
I still have to look at the code, but I will say that generating and using an API client based on an schema/api spec (my experience was with a go backend + protobuf definition with an elm frontend) was a real pleasure.

Is the legacy alert ingestion endpoint for a very old version of prometheus? If it's pre prometheus v1, I would be in favor of removing it.

Its for the current version of Prometheus.


A question: Do we want to deprecate the v1 api, or are we ok with just formalizing it with an openapi spec?


My question would be how would this work for Prometheus, as anything we do for the API in one place we're going to do in the other.

Brian
 

stuart

> To post to this group, send email to
--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.



--

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.



--

Max Leonard Inden

unread,
May 3, 2018, 3:35:14 AM5/3/18
to Prometheus Developers
> Is the legacy alert ingestion endpoint for a very old version of prometheus? If it's pre prometheus v1, I would be in favor of removing it.

As far as I can tell we moved away from the legacy "/api/alerts"
endpoint to "/api/v1/alerts" since Prometheus v0.17.0 [1][2].

> A question: Do we want to deprecate the v1 api, or are we ok with just formalizing it with an openapi spec?

I have also looked into extending the current Alertmanager v1 API via
Go-Swagger annotations but found it to be very hacky. I would prefer
starting from scratch for v2 and then deprecating v1 eventually. This
also gives us the possibility to take care of some technical dept in v1.
What do you think?



[1]
https://github.com/prometheus/prometheus/blob/master/notifier/notifier.go#L46
[2]
https://github.com/prometheus/prometheus/commit/e114ce0ff7a1ae06b24fdc479ffc7422074c1ebe



On 03.05.2018 08:18, Brian Brazil wrote:
> On 2 May 2018 at 22:40, Stuart Nelson <stuart...@gmail.com
> <mailto:stuart...@gmail.com>> wrote:
>
> I still have to look at the code, but I will say that generating and
> using an API client based on an schema/api spec (my experience was
> with a go backend + protobuf definition with an elm frontend) was a
> real pleasure.
>
> Is the legacy alert ingestion endpoint for a very old version of
> prometheus? If it's pre prometheus v1, I would be in favor of
> removing it.
>
>
> Its for the current version of Prometheus.
>
>
> A question: Do we want to deprecate the v1 api, or are we ok with
> just formalizing it with an openapi spec?
>
>
>
> My question would be how would this work for Prometheus, as anything we
> do for the API in one place we're going to do in the other.
>
> Brian
>  
>
>
> stuart
>
> On Tue, May 1, 2018 at 4:09 PM Brian Brazil
> <brian....@robustperception.io
> <mailto:brian....@robustperception.io>> wrote:
>
> On 1 May 2018 at 14:28, Max Leonard Inden <ind...@gmail.com
> prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>
> > <mailto:prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>>.
> > To post to this group, send email to
> > prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>
> > <mailto:prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>>.
> > To view this discussion on the web visit
> > https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com
> <https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com>
> >
> <https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com?utm_medium=email&utm_source=footer
> <https://groups.google.com/d/msgid/prometheus-developers/0b9527c6-79de-4063-af21-bb00dc577b6f%40googlegroups.com?utm_medium=email&utm_source=footer>>.
> > For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
> --
> You received this message because you are subscribed to the
> Google Groups "Prometheus Developers" group.
> To unsubscribe from this group and stop receiving emails
> from it, send an email to
> prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/f6ea9174-8145-75f5-fa5c-f07a52e74eb5%40gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/f6ea9174-8145-75f5-fa5c-f07a52e74eb5%40gmail.com>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>
>
>
> --
> Brian Brazil
> www.robustperception.io <http://www.robustperception.io>
>
> --
> You received this message because you are subscribed to the
> Google Groups "Prometheus Developers" group.
> To unsubscribe from this group and stop receiving emails from
> it, send an email to
> prometheus-devel...@googlegroups.com
> <mailto:prometheus-devel...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLpXM3s8fk0wo-21C6NXEaeGKJR8ZBUkRfGWfA8%3DXdBiPg%40mail.gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLpXM3s8fk0wo-21C6NXEaeGKJR8ZBUkRfGWfA8%3DXdBiPg%40mail.gmail.com?utm_medium=email&utm_source=footer>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>
>
>
> --
> Brian Brazil
> www.robustperception.io <http://www.robustperception.io>

signature.asc

Brian Brazil

unread,
May 3, 2018, 4:12:02 AM5/3/18
to Max Leonard Inden, Prometheus Developers
On 3 May 2018 at 08:35, Max Leonard Inden <ind...@gmail.com> wrote:
> Is the legacy alert ingestion endpoint for a very old version of prometheus? If it's pre prometheus v1, I would be in favor of removing it.

As far as I can tell we moved away from the legacy "/api/alerts"
endpoint to "/api/v1/alerts" since Prometheus v0.17.0 [1][2].

Ah, that we can kill then. The deprecation period for that has long passed.

> A question: Do we want to deprecate the v1 api, or are we ok with just formalizing it with an openapi spec?

I have also looked into extending the current Alertmanager v1 API via
Go-Swagger annotations but found it to be very hacky. I would prefer
starting from scratch for v2 and then deprecating v1 eventually. This
also gives us the possibility to take care of some technical dept in v1.
What do you think?

That seems sane to me, as long as alert ingestion keeps working.

Brian
 
> <mailto:stuartnelson3@gmail.com>> wrote:
>
>     I still have to look at the code, but I will say that generating and
>     using an API client based on an schema/api spec (my experience was
>     with a go backend + protobuf definition with an elm frontend) was a
>     real pleasure.
>
>     Is the legacy alert ingestion endpoint for a very old version of
>     prometheus? If it's pre prometheus v1, I would be in favor of
>     removing it.
>
>
> Its for the current version of Prometheus.
>
>
>     A question: Do we want to deprecate the v1 api, or are we ok with
>     just formalizing it with an openapi spec?
>
>
>
> My question would be how would this work for Prometheus, as anything we
> do for the API in one place we're going to do in the other.
>
> Brian
>  
>
>
>     stuart
>
>     On Tue, May 1, 2018 at 4:09 PM Brian Brazil
>             > To post to this group, send email to
>             > prometheus-developers@googlegroups.com
>             <mailto:prometheus-developers@googlegroups.com>
>             > <mailto:prometheus-developers@googlegroups.com
>             <mailto:prometheus-developers@googlegroups.com>>.
>
>             --
>             You received this message because you are subscribed to the
>             Google Groups "Prometheus Developers" group.
>             To unsubscribe from this group and stop receiving emails
>             from it, send an email to
>             To post to this group, send email to
>             prometheus-developers@googlegroups.com
>             <mailto:prometheus-developers@googlegroups.com>.

>             To view this discussion on the web visit
>
>         --
>         You received this message because you are subscribed to the
>         Google Groups "Prometheus Developers" group.
>         To unsubscribe from this group and stop receiving emails from
>         it, send an email to

>         To post to this group, send email to

>         To view this discussion on the web visit
--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/f9034515-25fb-bb54-7877-4c5e816e6658%40gmail.com.

For more options, visit https://groups.google.com/d/optout.



--

Stuart Nelson

unread,
May 3, 2018, 4:37:02 AM5/3/18
to Brian Brazil, Max Leonard Inden, Prometheus Developers
+1

On Thu, May 3, 2018 at 10:12 AM Brian Brazil <brian....@robustperception.io> wrote:
On 3 May 2018 at 08:35, Max Leonard Inden <ind...@gmail.com> wrote:
> Is the legacy alert ingestion endpoint for a very old version of prometheus? If it's pre prometheus v1, I would be in favor of removing it.

As far as I can tell we moved away from the legacy "/api/alerts"
endpoint to "/api/v1/alerts" since Prometheus v0.17.0 [1][2].

Ah, that we can kill then. The deprecation period for that has long passed.

> A question: Do we want to deprecate the v1 api, or are we ok with just formalizing it with an openapi spec?

I have also looked into extending the current Alertmanager v1 API via
Go-Swagger annotations but found it to be very hacky. I would prefer
starting from scratch for v2 and then deprecating v1 eventually. This
also gives us the possibility to take care of some technical dept in v1.
What do you think?

That seems sane to me, as long as alert ingestion keeps working.

Brian
> <mailto:stuart...@gmail.com>> wrote:
>
>     I still have to look at the code, but I will say that generating and
>     using an API client based on an schema/api spec (my experience was
>     with a go backend + protobuf definition with an elm frontend) was a
>     real pleasure.
>
>     Is the legacy alert ingestion endpoint for a very old version of
>     prometheus? If it's pre prometheus v1, I would be in favor of
>     removing it.
>
>
> Its for the current version of Prometheus.
>
>
>     A question: Do we want to deprecate the v1 api, or are we ok with
>     just formalizing it with an openapi spec?
>
>
>
> My question would be how would this work for Prometheus, as anything we
> do for the API in one place we're going to do in the other.
>
> Brian
>  
>
>
>     stuart
>
>     On Tue, May 1, 2018 at 4:09 PM Brian Brazil
>             <mailto:prometheus-developers%2Bunsu...@googlegroups.com>
>             > <mailto:prometheus-devel...@googlegroups.com
>             <mailto:prometheus-developers%2Bunsu...@googlegroups.com>>.
>             > To post to this group, send email to
>             > prometheus...@googlegroups.com
>             <mailto:prometheus...@googlegroups.com>
>             > <mailto:prometheus...@googlegroups.com
>             <mailto:prometheus...@googlegroups.com>>.
>
>             --
>             You received this message because you are subscribed to the
>             Google Groups "Prometheus Developers" group.
>             To unsubscribe from this group and stop receiving emails
>             from it, send an email to
>             To post to this group, send email to
>             prometheus...@googlegroups.com
>             <mailto:prometheus...@googlegroups.com>.

>             To view this discussion on the web visit
>
>         --
>         You received this message because you are subscribed to the
>         Google Groups "Prometheus Developers" group.
>         To unsubscribe from this group and stop receiving emails from
>         it, send an email to

>         To post to this group, send email to
>         prometheus...@googlegroups.com
>         <mailto:prometheus...@googlegroups.com>.

>         To view this discussion on the web visit

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-devel...@googlegroups.com.
To post to this group, send email to prometheus...@googlegroups.com.



--

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-devel...@googlegroups.com.
To post to this group, send email to prometheus...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLqhF5cGK2DK4H__wL_1Zj6TWWzkCdnr6q9ZiMRb3jfi0w%40mail.gmail.com.

Krasimir Georgiev

unread,
May 3, 2018, 4:54:10 AM5/3/18
to Stuart Nelson, Brian Brazil, Max Leonard Inden, Prometheus Developers
btw there is already a request from users for the same in prometheus.


Krasi Georgiev

Simon Pasquier

unread,
May 4, 2018, 8:50:09 AM5/4/18
to Max Leonard Inden, prometheus-developers
IMHO this is a valid goal. The existing code isn't terribly complicated but OpenAPI brings nice features such as automatic input validation.
As Krasi mentioned, there's a similar request for Prometheus. Doing it first for the AlertManager API (which has a smaller surface) would provide some indication whether it is worth doing it for Prometheus too.
On the con side, it may be more work for distro maintainers as it pulls packages that aren't available in the distros yet.

You said that you attempted to port the existing API using annotations and it wasn't terribly clean. Would it be possible to model the existing v1 API (provided that we're happy with it) with OpenAPI? The question may be silly but I don't have any concrete experience with Swagger/OpenAPI.

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com.

Max Leonard Inden

unread,
May 10, 2018, 2:45:15 PM5/10/18
to Simon Pasquier, prometheus-developers
> You said that you attempted to port the existing API using annotations and it wasn't terribly clean. Would it be possible to model the existing v1 API (provided that we're happy with it) with OpenAPI? The question may be silly but I don't have any concrete experience with Swagger/OpenAPI.

Replacing the current API (v1) with an interface-identical OpenAPI
implementation will be difficult. I am not sure this would result in a
clean design while keeping all the specialities of the current v1.
> send an email to prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>

signature.asc

Brian Brazil

unread,
May 10, 2018, 2:54:21 PM5/10/18
to Max Leonard Inden, Simon Pasquier, prometheus-developers
On 10 May 2018 at 19:45, Max Leonard Inden <ind...@gmail.com> wrote:
> You said that you attempted to port the existing API using annotations and it wasn't terribly clean. Would it be possible to model the existing v1 API (provided that we're happy with it) with OpenAPI? The question may be silly but I don't have any concrete experience with Swagger/OpenAPI.

Replacing the current API (v1) with an interface-identical OpenAPI
implementation will be difficult. I am not sure this would result in a
clean design while keeping all the specialities of the current v1.

Even if we allow differences in error handling? Keeping changes minimal for users as we iterate over time would be good.

Brian 
>     To post to this group, send email to
>
>

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/0ea16e13-99a6-4f4c-20de-74944cf6a053%40gmail.com.

For more options, visit https://groups.google.com/d/optout.



--

Callum Styan

unread,
May 23, 2018, 4:11:13 PM5/23/18
to Brian Brazil, Max Leonard Inden, Simon Pasquier, prometheus-developers
Are you still working on this Max? I'd be interested in helping out here if needed.

I haven't used swagger but I've had good experiences with other tools that generate the code for the API. If this would make alertmanager more maintainable long term and provide better API documentation then I think it's a good idea.


Replacing the current API (v1) with an interface-identical OpenAPI
implementation will be difficult. I am not sure this would result in a
clean design while keeping all the specialities of the current v1.
Can you give an example of something from the current API that wouldn't port nicely?


>     To post to this group, send email to
>     prometheus-developers@googlegroups.com
>
>

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsubscri...@googlegroups.com.

To post to this group, send email to prometheus-developers@googlegroups.com.



--

--
You received this message because you are subscribed to the Google Groups "Prometheus Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsub...@googlegroups.com.
To post to this group, send email to prometheus-developers@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLq_EasnYThBOmL4cocdaYJ6PGAQt--3i22eHW2-iww%2Bvg%40mail.gmail.com.

Max Leonard Inden

unread,
May 28, 2018, 6:09:07 AM5/28/18
to Callum Styan, Brian Brazil, prometheus-developers
> Even if we allow differences in error handling?

Allowing differences in error handling sounds like a breaking change to
me. Thereby I would prefer to bump the API version to v2, instead of
changing the API v1 behaviour. What do you think Brian?

> Keeping changes minimal for users as we iterate over time would be good.

For sure. I will try my best.

> Are you still working on this Max?

Yes, I am still working on this on the side.

> I'd be interested in helping out here if needed.

Cool, thanks! It would be a great help to get some feedback on my
proposal PR [1]. If you have time, please try it out and let me know how
it works for you. Keep in mind, that this is a work in progress PR and
that it is not yet feature complete with the Alertmanager API v1.

> Can you give an example of something from the current API that wouldn't port nicely?

I still have to wrap my head around the OpenAPI error handling logic but
other than that I think everything could technically be ported. I would
like to avoid carrying over some technical dept from the old API (v1)
like the alert groups endpoint. That is why I am suggesting the version
bump to v2, instead of replacing v1 with an identical implementation.


[1] https://github.com/prometheus/alertmanager/pull/1352



On 23.05.2018 22:11, Callum Styan wrote:
> Are you still working on this Max? I'd be interested in helping out here
> if needed.
>
> I haven't used swagger but I've had good experiences with other tools
> that generate the code for the API. If this would make alertmanager more
> maintainable long term and provide better API documentation then I think
> it's a good idea.
>
> Replacing the current API (v1) with an interface-identical OpenAPI
> implementation will be difficult. I am not sure this would result in a
> clean design while keeping all the specialities of the current v1.
>
> Can you give an example of something from the current API that wouldn't
> port nicely?
>
> On Thu, May 10, 2018 at 11:54 AM, Brian Brazil
> <brian....@robustperception.io
> <mailto:brian....@robustperception.io>> wrote:
>
> On 10 May 2018 at 19:45, Max Leonard Inden <ind...@gmail.com
> prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>
> >   
>  <mailto:prometheus-developers%2Bunsu...@googlegroups.com
> <mailto:prometheus-developers%252Buns...@googlegroups.com>>.
> >     To post to this group, send email to
> >     prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>
> >     <mailto:prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>>.
> >     To view this discussion on the web visit
> >     https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com>
> >   
>  <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com>>.
> >     For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>
> >     <https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>>.
> >
> >
>
> --
> You received this message because you are subscribed to the
> Google Groups "Prometheus Developers" group.
> To unsubscribe from this group and stop receiving emails from
> it, send an email to
> prometheus-devel...@googlegroups.com
> <mailto:prometheus-developers%2Bunsu...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/0ea16e13-99a6-4f4c-20de-74944cf6a053%40gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/0ea16e13-99a6-4f4c-20de-74944cf6a053%40gmail.com>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>
>
>
> --
> Brian Brazil
> www.robustperception.io <http://www.robustperception.io>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Prometheus Developers" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to prometheus-devel...@googlegroups.com
> <mailto:prometheus-devel...@googlegroups.com>.
> To post to this group, send email to
> prometheus...@googlegroups.com
> <mailto:prometheus...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLq_EasnYThBOmL4cocdaYJ6PGAQt--3i22eHW2-iww%2Bvg%40mail.gmail.com
> <https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLq_EasnYThBOmL4cocdaYJ6PGAQt--3i22eHW2-iww%2Bvg%40mail.gmail.com?utm_medium=email&utm_source=footer>.
signature.asc

Brian Brazil

unread,
May 28, 2018, 6:11:58 AM5/28/18
to Max Leonard Inden, Callum Styan, prometheus-developers
On 28 May 2018 at 11:09, Max Leonard Inden <ind...@gmail.com> wrote:
> Even if we allow differences in error handling?

Allowing differences in error handling sounds like a breaking change to
me. Thereby I would prefer to bump the API version to v2, instead of
changing the API v1 behaviour. What do you think Brian?

It is a breaking change, but I'd be far happier having a new API if everything else worked the same as it'll be easy for most users to upgrade.

Brian
 
>         >     To post to this group, send email to
>         >     prometheus-developers@googlegroups.com
>         <mailto:prometheus-developers@googlegroups.com>
>         >     <mailto:prometheus-devel...@googlegroups.com
>         <mailto:prometheus-developers@googlegroups.com>>.

>         >     To view this discussion on the web visit
>         >     https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com
>         <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com>
>         >   
>          <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com
>         <https://groups.google.com/d/msgid/prometheus-developers/59f721ce-d41a-4051-fc00-1eeaa1c99213%40gmail.com>>.
>         >     For more options, visit https://groups.google.com/d/optout
>         <https://groups.google.com/d/optout>
>         >     <https://groups.google.com/d/optout
>         <https://groups.google.com/d/optout>>.
>         >
>         >
>
>         --
>         You received this message because you are subscribed to the
>         Google Groups "Prometheus Developers" group.
>         To unsubscribe from this group and stop receiving emails from
>         it, send an email to

>         <mailto:prometheus-developers%2Bunsu...@googlegroups.com>.
>         To post to this group, send email to

>         To view this discussion on the web visit
>     --
>     You received this message because you are subscribed to the Google
>     Groups "Prometheus Developers" group.
>     To unsubscribe from this group and stop receiving emails from it,
>     To post to this group, send email to

>     To view this discussion on the web visit



--
Reply all
Reply to author
Forward
0 new messages