This point ends up being a little unclear due to the addition of the quote.
The quote is great, but perhaps it should be removed from this principles document to aid clarity for all.
The key point here is that consistency is great, but....
We won’t force unrelated interfaces or data structures to be identical if it makes them harder to use.
Ping @EProdromou (WMF). I wonder if you have some thoughts on alternate wording?
This point also doesn't immediately make sense, I'd love to see the text in bold being able to inform the reader of the principle, without needing to read the rest of the sentence. I guess this would go in the direction of "Return useful pre processed output" or something similar.
+1. Pre-chew the food doesn't translate over to the principle for me personally.
Based on our discussion of comments, I added a note about using "null" for empty properties.
I VERY strongly disagree with this. This is a really bad approach for frontend caching. Allowing people to request the same resource from multiple URIs a) split the cache b) make it next to impossible to effectively purge pages. Instead, we should aim for having 1 canonical URI for the resource, and redirect all non-canonical URIs to that representation, and cache the redirect. This will encourage clients to use normalized versions of the identifiers (title is a big example) to avoid paying the prize of roundtrips. Obviously, we all the identifiers we return must be (have a) canonical.
So, first, none of the endpoints we have right now use this, so it's a good time to discuss it.
I'm interested in how front-end caches use the Location: header with 200 statuses. I'll take a look.
According to https://tools.ietf.org/html/rfc7231#section-7.1.2 only specifies the meaning of the Location header for 201 and 3xx resources. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location phrases is more strictly "It only provides a meaning when served with a 3xx (redirection) or 201 (created) status response" So, Location with 200 is meaningless and doesn't follow the standard.
I was thinking of Content-Location. I've updated the page to reflect that; thanks for the links. I realise that the question of whether it's a good idea still stands.
I actually just removed the item entirely (here's what it used to say: "200 with Location: header for synonyms. If an object is available at more than one URL, operations on the secondary URL should return the object’s value with a Location: header to identify the primary URL. Most clients won’t be expecting 3xx redirects, so use 200 OK instead.").
We don't have any synonyms so far in the user stories for the Core REST API. I think the most likely situation would be with pages; having "/page/{id}/by-id" or something similar for getting a page by numeric ID.
On the client side, dealing with redirects sucks. You have to put a lot of extra code in to check if you got a redirect back, and then handle those cases. Just returning the content, with a header that tells intermediaries what the best URL to use is, is more developer-friendly.
I definitely understand the cache-friendliness question, though.
The `Content-Location` header is VERY useful and IMHO we should have a general rule of providing the Content-Location with every 200 response. One of the big benefits of having it is that browsers follow redirects automatically, so if we to adopt 3xx redirects, the browser clients will have an opportunity to know where were they redirected.
> We don't have any synonyms so far in the user stories for the Core REST API.
Yes we do. Even the `/page/{title}/history` is already a source of indefinite number of synonyms. We have never specified what format the '{title}' has to use - currently and combination of capitalization, spaces vs underscores and A TONS of different other normalizable alternatives will be accepted. If we had client side caching, this would've split the cache. Purging might be possible with `x-key` headers set to a normalized version. Normalizing URIs according to MW on the cache itself is impractical (just title normalization is 1000 lines of JS and it highly depends on the individual wiki config)
> You have to put a lot of extra code in to check if you got a redirect back
No you don't. Browsers don't even allow you no NOT follow the redirect. Almost all HTTP client implementations I have ever seen would either have a simple 'followRedirect' option or will follow redirect automatically.
I really like this document and I think we should expand it as much as possible. This has the potential to be the greatest time-saver ever :)
I feel like we could take https://google.github.io/styleguide/jsoncstyleguide.xml as an inspiration of where to drive this. Not copy all the decisions in there obviously, but document every decision as it arises. That includes "include null rather then omit the property" or "the concept of an anon has a keyword "anonymous" in all the API parameters. Having a document like this has several benefits:
- We only need to bikeshed once
- When REST APIs are developed not only within the team, but by extension developers and volunteers, we'd have a very comprehensive guide on how to do it.
I don't propose writing it all at once, but instead adding pieces as the decisions arise. What do you think?
I really like the iterative approach. We've already done it a few times with things like caching headers and object composition.
There's a lot of comments on the google doc https://docs.google.com/document/d/1SX204J8zdbCiJu9ttuz-i_Al3emY-3-mDk9EHvAkqrg/edit# where this has been copied from. None of them seem resolved, so they should be carried over to here
I just blanked the document. I'll let Daniel and Tim go back through this wiki page and see if they want to bring back up any of the unresolved topics from that discussion.
