News for hackers. Stuff that matters.
Re:Best practices for REST API design (2020) by seliopou on Monday February 22, 2021 @10:55AM (#26225927)
I interrupted my reading at 'Accept and respond with JSON' to write this comment, before I skipped over that section and returned to reading the rest.

Folks that aren't aware of Webmachine should take a look:

https://github.com/webmachine/webmachine

The 'Accept' header should determine the response type, but content negotiation is something that few bother to implement. Webmachine does that for you, among other things like choosing the correct status code for your response.

Also, shameless plug for my OCaml port:

https://github.com/inhabitedtype/ocaml-webmachine

Re:Best practices for REST API design (2020) by spelunker on Monday February 22, 2021 @12:15PM (#26227070)
> Webmachine is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb, and provides a simple and clean way to connect that to your application's behavior.

Great buzzwords, I have no idea what this project actually does.

Re:Best practices for REST API design (2020) by resonantjacket5 on Monday February 22, 2021 @04:34PM (#26230967)
I think its about adding semantic web stuff for mochiweb servers in their response? After clicking through a couple links I'm still not quite sure what it does.
[dead]
Re:Best practices for REST API design (2020) by Toutouxc on Monday February 22, 2021 @12:56PM (#26227725)
> For you and other non-programmers

> Once you've learned these two, the sentence immediately becomes clear

> it can sound like mumbo-jumbo, but I'm sure it makes sense for them, since they are professionals

Did you just link a person to a two-kilometer long page about HTTP, assumed they're not a programmer and almost accused them of not being professional enough, because they haven't heard of some Erlang library?

> application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management

I'm a web developer and my reaction was exactly the same. What the heck does this thing actually do?

Re:Best practices for REST API design (2020) by capableweb on Monday February 22, 2021 @01:08PM (#26227928)
> Did you just link a person to a two-kilometer long page about HTTP, assumed they're not a programmer and almost accused them of not being professional enough, because they haven't heard of some Erlang library?

Nope, I linked to a specific section of a HTTP specification that goes through "Content Negotiation" since that was what the topic was about and I wanted to share a resource to spelunker so they could read more about it, as if you're familiar with the topic, what seliopou wrote is not alien.

Re:Best practices for REST API design (2020) by pionar on Monday February 22, 2021 @12:59PM (#26227790)
I'm a programmer, and I know HTTP quite well. I know what HTTP semantics are, and this sentence is still gibberish to me.

I'd wager the reason I don't is because I'm not that familiar with the erlang ecosystem, so have no idea what mochiweb is, and don't know what this does differently.

Your first sentence was quite condescending, FYI, not sure if it was meant to be.

Re:Best practices for REST API design (2020) by capableweb on Monday February 22, 2021 @01:10PM (#26227969)
> Your first sentence was quite condescending, FYI, not sure if it was meant to be.

No, it was not and thank you for flagging that. Is it condescending to assume one is not a web developer if they don't know content negotiation? I thought that was Web 101 and pretty much one of the first things you go through when learning about HTTP, but maybe things have changed as of late.

I'm sorry spelunker if my message came off as condescending, I have no real idea of your professional and was only trying to provide a resource to learn more, not to push anyone away.

Re:Best practices for REST API design (2020) by resonantjacket5 on Monday February 22, 2021 @04:49PM (#26231131)
I think you can safely assume most people on here are some sort of programmer or at least tech-related.

We know about content negotiation it's probably the `Webmachine` `HTTP semantic awareness` `bit-pushing` `HTTP syntax-management` and `mochiweb` that not many people would know.

I'm not sure if you're purposefully trying to be sarcastic but even your current comment is kinda scathing.

Re:Best practices for REST API design (2020) by dmitriid on Monday February 22, 2021 @06:00PM (#26231839)
webmachine, mochiweb etc. come from Erlang.

webmachine is one of the earliest libraries I'm aware of that tried to think carefully about HTTP semantics and structured it's work with restful APIs (or web requests in general) according to an actual diagram that you can see here: https://github.com/basho/webmachine/blob/develop/docs/http-h...

There's an expanded and re-worked version that builds on this here: https://github.com/for-GET/http-decision-diagram/tree/master... (follow the links to system, request etc. to see the reasoning and references for each step)

Re:Best practices for REST API design (2020) by spelunker on Monday February 22, 2021 @11:55PM (#26233952)
Thanks, I'm a programmer professionally, and I broadly understand HTTP and the language of the web. Talking down to me is really helpful though.

It's true, I don't know erlang, or mochiweb, or the nitty-gritty of content negotiation, but OP presented this library as an alternative to "accept and respond with JSON" so I attempted to read the readme because I was curious. And then quickly lost my curiosity when I again, had no idea what this library actually did. If a readme is meant to be an inviting and basic overview of what a library does and why I should use it, the readme failed.

Re:Best practices for REST API design (2020) by Longwelwind on Monday February 22, 2021 @11:41AM (#26226544)
What is the usefulness of this feature?

The only advantage I see is that your clients can choose the format they want to work with, but since the serialization format is just a message format that has no impact on the code, and that most of them have a bijective transformation between them, I don't see the point.

If it feels like a lot of work (Or the added complexity of a moving part, if using the tool you linked) for next to no impact.

Re:Best practices for REST API design (2020) by dec0dedab0de on Monday February 22, 2021 @12:45PM (#26227558)
things like this are useful if you have a user that is integrating your api into some kind of legacy application that does not support json. Then in the future when JSON goes out of style, you could easily add support whatever the new format is.
Re:Best practices for REST API design (2020) by pionar on Monday February 22, 2021 @01:04PM (#26227870)
If you don't care about others using your API, then don't do it. If you do, follow the standard which says you SHOULD have a Content-Type if there is a body to your response.
Re:Best practices for REST API design (2020) by Longwelwind on Tuesday February 23, 2021 @03:12AM (#26234928)
My comment was about whether it's worth supporting multiple values for the "Accept" header, not the "Content-Type" header.
Re:Best practices for REST API design (2020) by trevor-e on Monday February 22, 2021 @11:43AM (#26226579)
I've read through the README and links and still have no idea what webmachine does.
Re:Best practices for REST API design (2020) by dec0dedab0de on Monday February 22, 2021 @12:38PM (#26227438)
Django REST Framework has this built in, and is very easy to turn on. I always turn it on even though my users almost exclusively use json. I had one user use xml once, because they didnt know how to use json in whatever it was they were using. Noone has ever used yaml, but i leave it there just in case.

if you do it right, using the standard html content type returns a human browseable representation of your api with forms for posts and whatnot.

Re:Best practices for REST API design (2020) by NanoWar on Monday February 22, 2021 @04:02PM (#26230577)
Omg I love the browsable api of Django. I am searching for something similar for .NET - any pointers anyone?
Re:Best practices for REST API design (2020) by slimbods on Tuesday February 23, 2021 @02:23PM (#26241624)
Re:Best practices for REST API design (2020) by NanoWar on Sunday February 28, 2021 @02:39PM (#26296343)
That's not browsable. Swagger is just a prefilled Postman. I mean some UI where I can navigate and discover the resources directly.
Re:Best practices for REST API design (2020) by dmitriid on Monday February 22, 2021 @11:05AM (#26226056)
> The 'Accept' header should determine the response type

Also, the HTTP decision diagram: https://github.com/for-GET/http-decision-diagram/tree/master...