• (nodebb)

    The bit about the templating language (or maybe the particular use of it) that bothers me is:

    {{#returnType}}

    vs

    {{/returnType}}

    vs

    {{^returnType}}

    To describe that as merely "opaque" would be a gross understatement.

  • DQ (unregistered)

    I recently had to write a program to consume an API. The response I get is like this

    {

    "result": "{"result": ...}",

    "status": 200

    }

    I guess they never heard about HTTP status codes.

  • (nodebb)

    I'm confused, first of all, what language is this? How are template placeholders filled in, like, at what stage, using what data source? Or this is part of some "eval" thing?

  • (nodebb) in reply to Mr. TA

    The templating language is Mustache.

    {{#returnType}}...{{/returnType}} is a section that is rendered if returnType exists and is not false or an empty list.

    {{^returnType}}...{{/returnType}} is a section that is rendered if returnType doesn't exist or is false or an empty list.

    It seems Mustache is used here for automatic generation of API clients, which I don't particularly hate.

    Addendum 2025-08-19 09:38: As for how the data gets filled in, it is as usual for templates: you pass the template and the data to the renderer, and it returns the rendered template as a string. Since this is a generator of API clients, I assume the generator code pulls the values of template variables from the API spec. At least, that's how openapi-generator works: it parses the OpenAPI spec and uses Mustache to generate a typesafe API client.

  • L (unregistered) in reply to Maia-Everett

    The templating language is Mustache.

    probably called like that because reading it ... must ache (ba-dum tss)

  • (nodebb) in reply to Maia-Everett

    Ah, OK, thanks. That explains it, although it doesn't explain why someone thought it wouldn't have been easier to read to say e.g.

    {{if NOT is_empty returnType}}
    ...
{{/if NOT is_empty returnType}}
  • (nodebb) in reply to Steve_The_Cynic

    Having just read some of the docs, it's not an if, it's a while. You can have multiple instances of returnType in your data and it will generate the enclosed section for each value. In this case, of course, you can probably have only one returnType and still get code that will compile.

  • (nodebb)

    Status codes are like phone numbers: they're numeric identifiers, not numbers. Too many people go "hey it's a number - I can do number-y things on it!". No! Bad programmer! No cookie!

  • Kotarak (unregistered)

    I came across a in-house API at my employer, which has a very creative way of using return codes. The API works basically like that: You trigger creation of a query process. This gives you the ID of the query. You may obtain from another endpoint the status of said query with the given ID. When the status finally says done, you can download the result of the query from a third endpoint. Why it is done that way? I don't know. I see all sorts of problems and overall it is just boilerplate where the user of the API has to entertain various bits and pieces, he is not interested in. But that is actually not the bad part.

    My first interaction with the API looked like this:

    1. Trigger query.
    2. Poll status: 200 => {"status": "processing this", ...}
    3. Poll status: 200 => {"status": "preparing that", ...}
    4. Poll status: 404 => {"status": "done", ...}

    Huh? I'm pretty sure that I used the same curl command for all of the polls. How can the URL suddenly be wrong? And why does it give a status on a supposedly non-existing query? Well, obviously this means that the query is done and that the result is empty. %-|

    Ok. Ok. But wait a second. What happens when you query a non-existing query ID? Well, then you get a 400. Says the documentation. Actually, you get a 500. Most likely because looking up a non-existing query ID somewhere raises an exception which bubbles all the way up to httpd, which thinks: "Oh. My request handler bailed out. Better let the client know."

    And now the sad part. They even had a rationale for this nonsense: When you receive a 404 you can skip the third query to obtain the data, because there is none. m( Why that information cannot be passed in the status is beyond me.

    Now, another developer and me lobbied for some changes. The 404 will be changed to 204. This is still wrong, because the status of the existing query exists and is not empty, but it's at least less wrong, if that means anything. Now I don't have to put normal connection handling into the error handler anymore.

  • (nodebb)

    @DQ ref

    I guess they never heard about HTTP status codes.

    No, no, no. HTTP status codes are for the HTTP protocol. and only the HTTP protocol. Did the server get an ungarbled request and send an ungarbled response? if so send a 200 as part of the HTTP envelope. NOT as part of the result.

    NEVER use HTTP status codes as API status codes. Even better, don't even try to ape the same numbers, e.g. 200=success, within your API. Substantially none of the other HTTP codes make any sense in API-space and importing just 200=success is essentially a brainfuck for your API consumers, inviting confusion and false expectations.

  • (author) in reply to WTFGuy

    Conditionally agree, but the underlying idea of a REST API specifically is that we're treating our API operations as operations on documents performed over HTTP. In that circumstance, I'd argue that you absolutely should be using HTTP status codes, because you're treating each API action as an HTTP request in a very real and literal way.

    But you should NEVER put the HTTP status code in your payload, 100%.

  • (nodebb) in reply to WTFGuy

    I had to fight that battle, exactly the same in every detail, two jobs ago. Ironically, my opponent was a smart guy, more experienced than me, but could not understand why he was wrong on this point.

  • Officer Johnny Holzkopf (unregistered) in reply to WTFGuy

    In case your API controls a coffee maker, HTTP 418 "I'm a teapot" is a tempting one to use... in case of... I don't know... split personality?

  • (nodebb)

    @Remy I agree/concede your point as to REST.

    With a side caveat that some RESTful APIs really ought not be done that way because the kinds of things the API performs on its end get waay beyond breaking the neat 1-to-1 mapping that is implicitly necessary in REST as a concept.

Leave a comment on “I Am Not 200”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article