redirection of POST /services and /jobs

[soxofaan]

from current API 1.0 docs about response on POST /jobs and POST /services:

201 The resource has been created successfully and the location of the newly created resource is advertized by the back-end.
Examples:

• POST /services redirects to GET /services/{service_id}
• POST /jobs redirects to GET /jobs/{job_id}
  Headers:
• Location: example Example: "https://openeo.org/api/v1.0/resource/123" URL to the newly created resource.

This is a bit confusing:

• The usage of "redirects" seems to suggest that backend should use a 3xx HTTP redirect (also note the "Location" header, which is classic 3xx), while it should be a "non-redirecting" 201
• the examples are also completely different and make it harder to connect the dots:
  -- above: /services/{service_id} and /jobs/{job_id}
  -- below: https://openeo.org/api/v1.0/resource/123

[soxofaan]

[m-mohr]

Location is also applicable for HTTP 201, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201. Is tells the back-end where the new resource can be found.

Indeed the examples are a bit misleading. The green area should better say "Mapping" instead of "Examples" and "points to" instead of "redirects to". The intentions was to show which endpoint should point to which resource. I'll fix that.

Does that help, @soxofaan ?

[soxofaan]

I would certainly avoid "redirect"

but the difference between the examples is still confusing:

• in the green area you have relative paths (with a HTTP verb "GET")
• in the example under "Location" it's an absolute url with this word "resource" in it (not obvious that this should be replaced with "services" or "jobs")

What is also not that obvious (or explicit) is that this "Location" url should be the "full metadata" endpoint. For example, I think in the VITO backend we return the WMTS base url here instead of the service metadata endpoint, which is wrong if I understand correctly

[soxofaan]

Can't you just move all examples to the "Location" header doc

e.g. something like:

Location:

• Example: "https://openeo.org/api/v1.0/resource/123"
• URL describing the newly created resource. For example: "https://openeo.org/api/v1.0/jobs/123" (For jobs) or "https://openeo.org/api/v1.0/services/123" (for services)

[m-mohr]

In the green area I am refering to the endpoints as defined in the OpenAPI file, the Location example is as concrete as possible with re-usable templates. So indeed it's meant to point to the metadata. Nevertheless, I'll issue a PR later and let you review.

[m-mohr]

Please review PR #269, @soxofaan. I tried to make it very clear now and actually splitted up the common definition into two parts.

[soxofaan]

great, thanks