That way of teaching got us to the moon, created transistors, produced the internet, smartphones, quantum computers, the very AI that everyone is talking about, vaccines, sent probes into space, cured diseases, fed millions, jumbo jets, basically every single thing that society has come to depend on.
In another comment, I mentioned that I was “the guy who knew about computers but was more approachable than the IT guy.” Even the rudest people tended to soften their tone when talking to me. I think when it comes to IT, most people’s default reaction is frustration. Trying to turn that frustration into a lesson can be frustrating at any age.
My approach was always: let me fix it first, then hand over the solution. It’s entirely up to you whether you want to follow up with “how did you fix it?” In my experience, 9 out of 10 people didn’t ask. The 1 out of 10 who did were often just making small talk.
The conversation was usually about how they ended up in that situation and what they wanted to achieve. I fixed they talked mostly to vent. That is part of the process.
In software engineering and professional culture, we often ask, “What have you tried so far?” That can be frustrating. The person you’re helping isn’t someone you have authority over—you either help them or you don’t. This cuts both ways, as they do not have authority on you to have you help them.
My thesis always has been people are generally polite. It’s not about manipulation or being overly conscious of achieving a goal. Impolite people usually are struggling with something internally, so you should pity them.
My Dad could never build the metal model to understand that common concepts like copy/paste would work almost identically across different native Windows applications; "How do I copy/paste in an email?", "How do I copy/paste in a Word document?", "How do I open a file in Excel?", "How do I open a file in Word?".
The lightbulb just never went on in his head. And this was in the 90s and early 2000s when developers at least used MFC - probably the period of peak UX design.
Things have now gotten so much worse since then. Now, I struggle to remember how to add an attachment in MS Teams, which I use every day.
Then that does not conform to the HTTP spec. GET endpoints must be safe, idempotent, cachable. Opening up a site to cases were web crawlers/scrapers may wreak havoc.
> Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs.
But it does though. A HTTP server returns a HTTP response to a request from a browser. The request is a HTML webpage that is rendered to the user with all discoverable APIs visible as clickable links. Welcome to the World Wide Web.
You describe how web pages work, web pages are intended for human interactions, APIs are intended for machine interaction. How a generic Python or JavaScript client can discover these APIs? Such clients will request JSON representation of a resource, because JSON is intended for machine consumption, HTML is intended for humans. Representations are equivalent, if you request JSON representations of a /users resource, you get a JSON list. If you request HTML representation of a /users resource you get an HTML list, but the content should be the same. Should you return UI controls for modifying a list as part of the HTML representation? If you do so, your JSON and HTML representations are different, and your Python and JavaScript client still cannot discover what list modification operations are possible, only human can do it by looking at the HTML representation. This is not REST if I understand the paper correctly.
> You describe how web pages work, web pages are intended for human interactions
Exactly, yes! The first few sentences from Wikipedia...
"REST (Representational State Transfer) is a software architectural style that was created to describe the design and guide the development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hypermedia system, such as the Web, should behave." -- [1]
If you are desiging a system for the Web, use REST. If you are designing a system where a native app (that you create) talks to a set of services on a back end (that you also create), then why conform to REST principles?
Most web apps today use APIs that return JSON and are called by JavaScript. Can you use REST for such services or does REST require a switch to HTML representation rendered by the server where each interaction returns new HTML page? How such HTML representation can even use PUT and DELETE verbs, as these are available only to JavaScript code? What If I design a system where API calls can be made both from the web and from a command line client or a library? Should I use two different architecture to cover both use cases?
> Most web apps today use APIs that return JSON and are called by JavaScript. Can you use REST for such services
You kind of could, but it's a bad idea. A core tenet of the REST architecture is that it supports a network of independent servers that provide different services (i.e. webpages) and users can connect to any of them with a generic client (i.e. a web browser). If your mission is to build a specialized API for a specialized client app (a JS web app in your example), then using REST just adds complexity for no reason.
For example, you could define a new content-type application/restaurantmenu+json and build a JS client that renders the content-type like a restaurant's homepage. Then you could use your restaurant browser JS client to view any restaurant's menu in a pretty UI... except your own restaurant's server is the only one that delivers application/restaurantmenu+json, so your client is only usable on your own page and you did a whole lot of additional work for no reason.
> does REST require a switch to HTML representation ... How such HTML representation can even use PUT and DELETE verbs
Fielding's REST is really just an abstract idea about how to build networks of services. It doesn't require using HTTP(S) or HTML, but it so happens that the most significant example of REST (the WWW) is built on HTTPS and HTML.
As in the previous example, you could build a REST app that uses HTTP and application/restaurantmenu+json instead of HTML. This representation could direct the client to use PUT and DELETE verbs if you like, even though these aren't a thing in HTML.
Thanks for the insight. This very well matches my experience from the top comment of this thread. I added discovery related functionality to JSON based API in an attempt to follow REST and didn't see any benefits from the extra work and complexity. Understanding that REST is inherently for HTML (or a similar hypertext based generic client) and it doesn't make sense to try to match it with JSON+JS based API is very refreshing. Even the article that sparkled this discussion gives example of JSON based API with discover related functionality added to it.
Keep in mind that Fielding used his "REST" principles to drive work on the release of HTTP 1.1 in 1999. He subsequently codified these RESTful principles in his dissertation in 2000. The first JSON message was sent in 2001. The reason RESTful is perfectly suited to the WWW is because REST drove HTTP 1.1, not the other way around.
Now days there are just so many use cases where an architecture is more suited to RPC (and POST). And trying to bend the architecture to be "more RESTful" just serves to complicate.
The simplest case, and the most common, is that of a browser rendering the HTML response from a website request. The HTML contains the URL links to other APIs that the user can click on. Think of navigating any website.
"I have one job on this lousy ship, it's stupid, but I'm gonna do it! Okay?" -- Sigourney Weaver
[1] - https://www.youtube.com/watch?v=W4CgQMJCpZI