.json endpoint may also be useful?

[tunnckoCore]

Returning something like that

{
  "code": 404,
  "message": "Not Found"
}

or even better, whole page to be represented as json, for example including the text description, and code references.

{
  "code": 404,
  "message": "Not Found",
  "description": "A 404 status code does not indicate whether this lack of...",
  "references": [
    "Rails HTTP Status Symbol :not_found",
    "Go HTTP Status Constant http.StatusNotFound"
  ]
}

[Caster]

This may be a duplicate of #36. I would like this. The references could also be an object, with

{
  "Rails HTTP Status Symbol": ":not_found",
  "Go HTTP Status Constant": "http.StatusNotFound"
}

for example. It is stored that way in the source, so might make more sense?

[shrink]

Thanks for the feedback! I've been intending on adding this functionality but I have been sidetracked from this project recently, I'll make time for this asap as there is more demand than I thought.

I have some questions for those interested in this functionality:

1. How should the description be formatted, is Markdown (how it appears in codes/410.md) minus the front matter optimal, or should it be provided in rendered HTML? Alternatively both could be provided, along with plain text. Any information on how you intend on consuming the API would help inform this decision.
2. The opening paragraph of each status code is emphasised on the site because the project guidelines require that the opening paragraph describe meaning, should this opening paragraph be available as its own value via the API. For example "meaning" (the opening paragraph) and "description" (the entire description) or should the consumer be responsible for any decision about which part is meaningful?
3. What is the most sane approach to providing the list of status codes, should they be grouped by class (eg: /4.json) or should they be provided all together (eg: /list.json) and the consumer is responsible for retrieving which class they are interested in?

Thanks!

[tunnckoCore]

@Caster The references could also be an object

Yea, I thought for this. But maybe it would be more useful keys to be just the language name for better access.

{
  "rails": ":not_found",
  "go": "http.StatusNotFound"
}

@citricsquid I like your questions. For the first one, I think that it make more sense all in the json response to be plain text and yes it make sense for separate values for meaning and description. But yea, it also be useful to have and the markdown formatted text - maybe markdown endpoint make sense?

What I'm thinking for now:

/404.json

{
  "code": 404,
  "message": "Not Found",
  "description": "A 404 status code does not indicate whether this lack of...",
  "meaning": "The origin server did not find a current representation for the target resource
or is not willing to disclose that one exists.",
  "references": {
    "rails": ":not_found",
    "go": "http.StatusNotFound",
    "node": "http.STATUS_CODES[404]"
  }
}

Also maybe make sense to add statusCode alias of code.

I'm not very sure, currently, how markdown endpoint can look like.

or should they be provided all together

maybe both, not sure.

[tunnckoCore]

Ooh, and maybe type property to answer what is the kind of error: "client error", "informational" and so on.

[Caster]

@tunnckoCore But maybe it would be more useful keys to be just the language name (...)

Yes, I fully agree. The only reason I used the other format is that that is what is in the Markdown right now, but that could be parsed out quite easily.

I like all other points you mention. For the plain text/Markdown/HTML question: maybe one could have /404.json with plain text, /md/404.json and /html/404.json or something along those lines?

So yes, I would be in favor of having a separate endpoint for every status code. It could be useful to have one large list with all codes, possibly ordered by category. I do not see a use for having a list per category (could be extracted easily from the large list anyway), but I may overlook something.

Example format:

[
  {
    "category": "Informational",
    "id": 1,
    "codes": [100, 101, 102]
  },
  {
    "category": "Success",
    "id": 2,
    "codes": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226]
  },
  {
    "category": "..."
  }
]

[tunnckoCore]

have /404.json with plain text, /md/404.json and /html/404.json

this not looks good, lol and not make sense. :laughing:

In addition to your example I think it also can have more advanced look, like not only the code, but code object like this for 404 for example.

[
  {
    "id": 4,
    "category": "Client Error",
    "codes": [..., {
      "code": 404,
      "message": "Not Found",
      "category": "Client Error",
      "description": "A 404 status code does not indicate whether this lack of...",
      "meaning": "The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.",
      "references": {
        "rails": ":not_found",
        "go": "http.StatusNotFound",
        "node": "http.STATUS_CODES[404]"
      }
    }]
  }
]

Maybe yours make more sense, but mine to be accessed with some query param.

edit: for example /list.json?codes=short as you shown it and /list.json?codes=long as I shown it. And yes, "short" should be default.

[Caster]

Maybe I should clarify. The /404.json would contain plain text description and meaning, the /md/404.json would have Markdown-formatted description and meaning, et cetera. This could also be done with /404.json?textformat=md or something like that... I just proposed this because it can be generated statically, which matches the rest of this repository. Anything works for me. How would you propose to do it?

The latter is of course an option, but would make for a huge response, which I personally would not like very much if you only need one or two codes. Query parameter would do it, but would of course require server-side code. Not sure if that is an option?

[tunnckoCore]

if you only need one or two codes

Then you request their endpoints, not the list endpoint, lol.

Maybe I should clarify. The /404.json would contain plain text description and meaning, the /md/404.json would have Markdown-formatted description and meaning, et cetera.

Haha, got it. Great idea. And it looks better than query params.

[shrink]

Thank you for sharing your thoughts. I'll formulate a plan over the weekend and report back here so that we can discuss further.

Something to note: because this is a static site it would be difficult to implement a parameter based API, the web server would need to be configured to use the parameters to determine which file and that adds complexity that I'm not sure is justifiable -- ideally this site is something anyone can deploy anywhere, just build and copy the files at its simplest.

[mgernand]

I just created a fork that provides an additional JSON endpoint, f.e. to get the JSON info of the 200 OK:

GET https://httpstatuscodes.io/200.json

The web page is available at https://httpstatuscodes.io/200