No, it’s not. That’s why we wrote “because of the limits of browser-native authentication (e.g. no logout, no styling), form-based authentication in conjunction with cookies can be used”. In practice, that’s the only option for public applications.
"The trope of 'software as a highly abstract, intellectually demanding, nearly mathematical activity' contributes to a myth of software development as a profession 'naturally' dominated by males: math is the subject of its own interlocking system of tropes, myths and stereotypes that paint it as a manly pursuit."
That logic seems to be all backwards to me. Of course developing software is a highly abstract, intellectually demanding activity. Claiming it’s not is as absurd as claiming women are somehow incapable of doing exactly that.
What I meant is that this is a particular kind of backend API, a very "model-centric" one. Nothing wrong with that, I just don't think this is the one and only kind and thus should take on the generic name.
> 2. If you're transitioning _to_ this kind from some sort of older kind.
Understood. Maybe an approach is to allow for this to specified optionally, with the fallback of being hard-coded if it's not present?
> You can think of the ID-based approach as just coming with a set of default URL templates in a top-level rel.
Then I'd be perfectly happy. But why is the paragraph that mentions exactly this ("... The top-level of a JSON API document MAY have the following keys") in the "URL-Based JSON API" section?
> You think a server SHOULD use HTTP caching?
No, you're probably right - a SHOULD is too strong. I guess my reaction was more negative to the "MAY" in your text about caching than anything else. The caching section (which is currently in the writing document?) doesn't seem to actually add much value beyond what HTTP says anyway. Maybe dropping it is the easiest path?
Why would you say something like that? There's no basis for that at all. From a REST POV, URIs are just opaque identifiers, the characters they're made up from don't matter a bit.
First, I think it's awesome that you guys are documenting this for others to re-use, whether it ends up being the one true format or not. Having options to choose from is doubtlessly good.
Some thoughts:
1. I'm not sure about the name. There will definitely many JSON APIs that don't use (your) JSON API for a long time, even if this becomes hugely popular. I don't see how this will not lead to avoidable confusion in the future. Given that it's very document-centric, why not use something like "JSON Doc API" or similar?
2. In the ID approach, why are the base URIs the client needs to know about not always discoverable, e.g. using standard link relations? Or phrased differently, why would I ever not want to use the "URL Template Shorthands" approach mentioned later?
3. Why use application/json and not something more specific? I can see some reasons, but would be interested in yours.
4. On creation, if I accept the pain of generating an ID on the client and can construct the URI using the template, why can't I use PUT instead of POST?
5. If I use a POST to create something, why don't I get a 201 Created with a Location header?
6. I'd suggest to upgrade the "MAY" for caching to a "SHOULD".
This is a pretty neat usage of a service that only makes sense because of the scaling ability of the underlying platform. I expect to see many more things of this kind.
First of all, make sure the client and you agree on what the long-term strategy is. Then get buy-in for a first step in this direction.
If the system is as bad as you make it sound, the long-term goal has got to be a complete replacement of the existing codebase. That will usually require as much effort, and thus money, as writing the existing version did. (Experience shows there's is no reason to confidently assume different.)
Then, explain how to get there without doing a (hopeless) complete rewrite in one big bang:
First, you need to make a set of decisions for the new code you're going to write, i.e. the language, framework(s), architecture, whatever you want to new code to be based on.
Next, you try to modularize the existing system so that you can replace one tiny part.
That's going to be really, really hard - modularizing a systems after it's in production always is. Don't do it all at once: If you've isolated some small piece of so that there's a clear interface (based on a programming language API, a database interface or (my favorite) some RESTful HTTP API), rewrite that small piece using your new technology stack and integrate it with the existing monstrosity.
Once you have done that successfully for some small aspect, you have some sort of proof that this approach can work.
Then, over the next months (or more likely: years), rinse and repeat.
This is a hugely expensive thing to do, but that shouldn't come as a surprise – after all, you're replacing the organs in a living body while it's running a marathon on its last breath. An MBA should understand that the additional cost is because this strategy drastically reduces the risk.
You can explain to the customer that they can try this out using just a small part, and decide whether or not they want to continue afterwards. Point out that you're going to start with those parts that produce most of the existing pain. Explain that you're helping them to return to a situation in which they have fewer bugs, can introduce new features quickly and easily, and best of all, that the end result will be a system that's modularized, hopefully ensuring that they won't run into the same situation again.
If they expect you to do magic, i.e. maintain the mess and magically turn it into a good piece of software without being allowed to actually change it significantly, get out of the contract as quickly as you can.
Can't explain this, other than what do you expect from a country that's still using checks? FWIW, Germany is similar to your country in this regard - entirely impossible to pay with your credit card anywhere without at least a signature.