1036225 - Return a link to the REST documentation in "method not found" errors

Status: RESOLVED FIXED

(Bugzilla :: WebService, defect)

Description

[Karl Dubost💡 :karlcow]

Currently when requesting the root of the API, two things happen:

1. We get a 200 OK
2. We get an error message, so basically contradicting the "200 OK".


→ http GET https://bugzilla.mozilla.org/rest/

HTTP/1.1 200 OK
Access-control-allow-headers: origin, content-type, accept
Access-control-allow-origin: *
Content-Encoding: gzip
Content-Length: 103
Content-Type: application/json; charset=UTF-8
Date: Wed, 09 Jul 2014 02:10:51 GMT
Etag: OP4JGZUOG6nkYGeU9b7x2A
Server: Apache
Strict-transport-security: max-age=31536000; includeSubDomains
Vary: Accept-Encoding
X-Backend-Server: web3.bugs.scl3.mozilla.com
X-content-type-options: nosniff
X-frame-options: SAMEORIGIN
X-xss-protection: 1; mode=block

{
    "code": 32614, 
    "error": true, 
    "message": "A REST API resource was not found for 'GET /'."
}


Suggestions:
(You could do one of these)

# Suggestion 1: Send back an error to the client.

If there is no representation then just say it. It doesn't forbid to explain why in the payload. 
http://tools.ietf.org/html/rfc7231#section-6.5.4

HTTP/1.1 404 Not Found
Content-Length: 103
Content-Type: application/json; charset=UTF-8

{
    "code": 32614, 
    "error": true, 
    "message": "A REST API resource was not found for 'GET /'."
}

PS: you could take this opportunity to have a link to the documentation (not sure it is the relevant docs)

{
    "code": 32614, 
    "error": true, 
    "message": "A REST API resource was not found for 'GET /'.", 
    "documentation": "https://wiki.mozilla.org/Bugzilla:REST_API"
}



# Suggestion 2: Send something more useful for the client to continue to operate.

When a human access https://bugzilla.mozilla.org/ s/he can do quite a few things. 
It is entirely possible to give a JSON representation with a 200 OK this time, helping the client to go on the next request. It could be things such as links to documentation, links to different features of the API, etc.

Comment 1

[:glob ✱]

> (You could do one of these)
i think we should do both :)

i've filed 1036268 to track fixing the http/200 issue.
morphing this bug slightly to track adding a link to the documentation to our response.

Comment 2

[David Lawrence [:dkl]]

Attachment: 1036225_1.patch

Comment 3

[:glob ✱]

Comment on attachment 8453174 [details] [diff] [review]
1036225_1.patch

Review of attachment 8453174 [details] [diff] [review]:
-----------------------------------------------------------------

i think this would be better implemented as a new field in the response as per karl's suggestion instead of appending to the error message.

Comment 4

[David Lawrence [:dkl]]

Attachment: 1036225_2.patch

I am not sure that pointing to wiki.m.o is the best link for the 'upstream' code as we should be promoting the docs that come with Bugzilla which hopefully reside on readthedocs.org as well in the future. We can change the constant on commit if you disagree at this time.

Also the version will need to be updated with stable release (currently tip).

dkl

Comment 5

[David Lawrence [:dkl]]

Attachment: 1036225_3.patch

Moved to Bugzilla/Constants.pm so it can be updated each time we release a new branch.

Comment 6

[:glob ✱]

Comment on attachment 8453817 [details] [diff] [review]
1036225_3.patch

Review of attachment 8453817 [details] [diff] [review]:
-----------------------------------------------------------------

r=glob perfect

Comment 7

[David Lawrence [:dkl]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   8dbd57d..551eb6d  master -> master