Agency POST response codes

[thekaveman]

Agency defines a number of POST endpoints that mention both 200 and 403 response codes, e.g. for POST /vehicles

Yet the common list of Responses that Agency docs also point to say this:

200: OK: operation successful. 201: Created: POST operations, new object(s) created ... 401: Unauthorized: Invalid, expired, or insufficient scope of token. 404: Not Found: Object does not exist, returned on GET or POST operations if the object does not exist. ...

1. 201 is mentioned here as what a successful POST should return, different from 200 in the Agency docs
2. 401 is mentioned here as what an unauthorized request should return, different from 403 in the Agency docs
3. 403 is not mentioned at all on the common list

There's lot of ink online about 401 vs. 403 (e.g. this SO post) and I don't mean to re-hash any of those conversations that have happened in MDS... but I think we should be consistent across docs.

FWIW: in the Provider OpenAPI doc, I've used 401 everywhere, since Provider docs don't mention 403 but they do point to the common list of Response codes, e.g: https://github.com/openmobilityfoundation/mds-openapi/blob/feat/provider/reference/provider.yaml#L68

[schnuerle]

We did have a big discussion on #838 about some response codes. @marie-x It seems we should be using 401 and we can remove 403 from the spec. Do you see any issue with that?

[marie-x]

We did have a big discussion on #838 about some response codes. @marie-x It seems we should be using 401 and we can remove 403 from the spec. Do you see any issue with that?

Sounds great!

[thekaveman]

@marie-x @schnuerle How about the difference between 200 and 201?

201 is mentioned here as what a successful POST should return, different from 200 in the Agency docs.

[schnuerle]

So remove 403 for sure.

What about 200 vs 201? Seems like 201 is valuable to have to ensure the item was created, vs the more generic 200 when all is ok. So both are good to keep?

[thekaveman]

So remove 403 for sure.

Done.

Seems like 201 is valuable to have to ensure the item was created, vs the more generic 200 when all is ok. So both are good to keep?

Yep, I'll keep both in the OpenAPI docs.

[schnuerle]

So should any 403s like in Vehicles in Agency, and in Jurisdiction, be changed to 401s? Or should 403s be removed completely?

[thekaveman]

Jurisdiction shouldn't have either, because it is public / shouldn't throw "Not authorized" errors.

In Agency (and Metrics, Provider) we should use 401 everywhere there could be an authorization error, and remove 403 entirely.

I think only the Agency docs in the spec need the update though.

[thekaveman]

This is done in the OpenAPI docs.

[schnuerle]

Everything mentioned here should be resolved as part of #856 so focusing on that Issue now.