Closed Bug 1036225 Opened 6 years ago Closed 6 years ago

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

Categories

(Bugzilla :: WebService, defect)

defect
Not set

Tracking

()

RESOLVED FIXED
Bugzilla 5.0

People

(Reporter: karlcow, Assigned: dkl)

References

()

Details

Attachments

(1 file, 2 obsolete files)

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.
> (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.
Assignee: nobody → webservice
Component: API → WebService
Product: bugzilla.mozilla.org → Bugzilla
QA Contact: default-qa
Summary: Improve the readability of the API through documentation → Return a link to the REST documentation in "method not found" errors
Version: Production → unspecified
Attached patch 1036225_1.patch (obsolete) — Splinter Review
Assignee: webservice → dkl
Status: NEW → ASSIGNED
Attachment #8453174 - Flags: review?(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.
Attachment #8453174 - Flags: review?(glob) → review-
Attached patch 1036225_2.patch (obsolete) — Splinter Review
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
Attachment #8453174 - Attachment is obsolete: true
Attachment #8453719 - Flags: review?(glob)
Attached patch 1036225_3.patchSplinter Review
Moved to Bugzilla/Constants.pm so it can be updated each time we release a new branch.
Attachment #8453719 - Attachment is obsolete: true
Attachment #8453719 - Flags: review?(glob)
Attachment #8453817 - Flags: review?(glob)
Comment on attachment 8453817 [details] [diff] [review]
1036225_3.patch

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

r=glob perfect
Attachment #8453817 - Flags: review?(glob) → review+
Flags: approval+
OS: Mac OS X → All
Hardware: x86 → All
Target Milestone: --- → Bugzilla 5.0
To ssh://gitolite3@git.mozilla.org/bugzilla/bugzilla.git
   8dbd57d..551eb6d  master -> master
Status: ASSIGNED → RESOLVED
Closed: 6 years ago
Resolution: --- → FIXED
See Also: → 1057774
You need to log in before you can comment on or make changes to this bug.