The thing that annoys me is the response. It should return status 201 created and the id of the new resource for future delete/update operations. Instead it returns 200 ok and some clear text. Wouldn't want to work with such an API.
/serious Well, yes, most APIs are meant for system-to-system interaction, that's kind of a given. But since this particular API is clearly meant for human-to-system interaction, returning a human-readable response is adequate. Yes, a better design would probably allow the client to specify additional parameters about the desired response.
/back-to-jokes Yeah, well this kind of sums up most of my job applications. I send an application and the recruiting people are all like "OK".
Hey, that's me! I query my workforce data from the HRIS with M and SQL. In HR land, that makes me a super senior data scientist compared to VLOOKUP guy who hasn't even heard of XLOOKUP or even INDEX/MATCH, that asshole.
One interesting question to others here: Would you agree with the line under this comparison that the HTML response is self-describing?
Because frankly... I kinda don't. You need an interpreter to make sense of it, namely a web browser that knows the HTML-specification and can translate the HTML tags into meaningful semantics. But the moment I need that, I could also have a JSON interpreter in my system that uses a DSL we use internally to make sense of the JSON received, no? It's essentially the same thing.
Yeah, HTML only makes sense in the context of a hypermedia system. They explain it in the book titled so. The main point, I think, is that JSON API consuming clients are too thick (for most purposes they're trying to achieve) which slows down development, adds unnecessary complexity and causes developer fatigue.
I also notice that the job you apply for seems to be a different value than what is displayed on the page. Seems like the documentation needs updating as well 😔