Ability to provide HTTP verb for affectedEndpoints

[Colin-b]

A single /test endpoint may be available in more than one HTTP verb (amongst GET, POST, PUT, DELETE, PATCH most of the time). And the check may be related to only a subset of those verbs.

As of now there is no way to provide the HTTP verb(s)

[inadarei]

I have mixed feeling about it. We'll have to discuss how/if it can be implemented in the next version.

Thank you

[smoyer64]

There are actually two ways to do this:

1. Use the verb as part or all of the measurementName per section 4 of the specification.

2. Provide the verb as one of the fields in the checks objects as described by section 4.10 of the specification.

[inadarei]

I think the cleanest way would be:

to extend this

"affectedEndpoints" : [
          "/users/{userId}",
          "/customers/{customerId}/status",
          "/shopping/{anything}"
        ],

to this

"affectedEndpoints" : [
          {"/users/{userId}": ["GET", "PUT"]},
          "/customers/{customerId}/status",
          {"/shopping/{anything}": ["PATCH", "POST"}
        ],

where if the element of "afectedEndpoints is a string rather than an object a "GET" is assumed. So "/customers/{customerId}/status" as an element in the array becomes equivalent to {"/customers/{customerId}/status" : ["GET"]

This would make the enhancement backwards-compatible but parsing will be significantly more awkward than if we insisted every element to always be an object. It will probably make parsing very painful for strictly-typed languages. JSON RFC states that it is legal: "There is no requirement that the values in an array be of the same type." but that doesn't mean it is nice to do such things.

I know parsing mixed array will be no problem in JS/Node or Python. I know it will be super annoying but doable in Go. Would love to hear from people who use Java and .Net regularly. I assume it will at the bery least be error-prone.

If we assume that most people will not care for the level of detail of HTTP verbs then for the sake of backwards compatibility having mixed elements makes sense, but parsing implications make me worry about it a lot.

[smoyer64]

That is indeed horrible for languages that are automatically marshaled/unmarshaled to types ... in Go you'd have to unmarshaled them to json.RawMessage and then attempt to unmarshal each element to the object and then fall-back to the string (or vice-versa). In Java (and I believe .NET), you'd have to do basically the same thing (though the mechanism is different). I think it's important that this specification be friendly to strictly typed languages so that there is broad adoption.

As an aside, in Go section 4.10 is already a pain-in-the-neck. These are called "additional properties" in the jsonschema.org guidelines but, while Go can easily handle optional keys, it's not so easy to handle arbitrarily added keys. Sometimes it's simplest to go back to map[string]json.RawMessage and unmarshal some fields further.

[peteraritchie]

Some thoughts:
The Web Linking RFC (8288) goes into some details that might be useful here (with some JSON-specific detail in JSON Serialization for Web Linking).
The basic link structure, in JSON, would look like this:

[ 
  {
    "href": "/user/{userId}"
  }
]

usually in a context like this:

{
  "links": [{"href": "/user/{userId}"}]
}

And that detail can be added to include things like title and rel. It's rel that has the detail about HTTP method.
e.g.

  "affectedEndpoints": [ 
    {
      "href": "/user/{userId}",
      "rel": "item"
    }
  ]

would be a standard way to like to something that would be accessed with GET by the semantics of "item" relation.

Additionally...

  "affectedEndpoints": [ 
    {
      "href": "/user/{userId}",
      "rel": "create-item"
    }
  ]

This would be a standard way to link to something that would be accessed with POST by the semantics of "create-item" relation.

Alternatively, 8288 does detail some serialization-specific attributes that may be used to convey the attributes of the target. e.g.

  "affectedEndpoints": [ 
    {
      "href": "/user/{userId}",
      "type": "POST"
    }
  ]

Here type is used to convey that this is a type of POST.

The later seems to be a convention in RESTful circles [restful-hateoas].

In either case, each method (verb) would be a separate entry:

  "affectedEndpoints": [ 
    {
      "href": "/user/{userId}",
      "type": "POST"
    },
    {
      "href": "/user/{userId}",
      "type": "GET"
    },
    {
        "href": "/shopping/{anything}",
        "type": "PATCH"
    },
    {
        "href": "/shopping/{anything}",
        "type": "POST"
    },
  ]

Collection+JSON - Document Format is also interesting with regards to supporting query strings in the web link.