HNHacker News
TopNewBestAskShowJobs

smizell

112 karma · joined September 12, 2013

submissionscomments
smizell··on Ask HN: What are the books that changed the perspective of your life?
I thought the same of Orthodoxy. Chesterton just has a way with words and thoughts.
smizell··on The thing I hate about HTML (2010)
Hiccup gives you HTML in Lisp https://github.com/weavejester/hiccup
smizell··on APIs.io – The API search engine
Definitely! :) Was just pointing out that this search engine was making discovery possible _because_ of hypermedia. Nicely done!
smizell··on APIs.io – The API search engine
I think a key here is hypermedia. APIs can only be machine-discoverable if there are hypermedia links pointing to them (which is how this helps). If there are no links, then some human must hardcode it.

This also is a reason for including hypermedia in your API, because really, being machine-discoverable is not just something that the API itself benefits from... each resource and state can benefit from included hypermedia as well.

smizell··on Virtual DOM in Elm
Cool, I'll keep an eye out. Any reason to use React+Mori over Om other than more familiarity with JavaScript??
smizell··on Virtual DOM in Elm
Do you have any code samples online of this combination? I'd be interested to see how these are used together, because they seem like a great fit.
smizell··on Ask HN: What would attract you to a job in flyover country?
I live and work in the Midwest, and this is the situation I see a lot. We actually saw a local company move to a nearby city (two hours away) in order to find more talent, though they bumped up the salary to get that talent. I believe if they would have offered that higher salary here, they would have been fine (we actually have a university in our town).

The hard part is, instead of asking, "What is the value of my work?" you have to ask "What is the value of my work here?" It's a very odd question to ask if you work for a company that is in national or global markets.

smizell··on Dart 1.5
I think Blossom [1] switched to it. They had some articles on their blog about the switch [2].

[1] https://www.blossom.io/ [2] http://www.ramen.io/post/46936028144/we-are-switching-to-dar...

smizell··on Solving FizzBuzz with Hypermedia
(author here) It definitely does! But the point was to play with hypermedia (REST), not really solve FizzBuzz.
smizell··on The lie of the API
This is also how Apache works with content negotiation, either with a type map or MultiView.

https://httpd.apache.org/docs/current/content-negotiation.ht...

smizell··on The lie of the API
Regarding content negotiation, the idea is to put all of the media types in the Accept header that the client can understand (instead of saying I want such and such representation). You then request a URI and the server decides which representation of that resource to return in the response based on those headers. I think you may have mentioned most of this, but I reiterate to say that if a client cannot do this, it's to the fault of the client. The web was built to work with content negotiation and it does this beautifully.

With that said, there is nothing wrong with linking to the HTML file with .html, but the developer (or user) consuming the API (or website) should not be adding suffixes to get the representation they want... the API should be returning those URLs in the response.

Additionally, regarding screen scraping, HTML coupled with something like RDF, Schema.org, or other microformats/microdata allows you to parse the HTML looking for that data without breaking clients on HTML changes. It really is a good media type for REST, which does seem odd at first and does feels like screen scraping, but you're just parsing the HTML like you would XML. The difference is HTML is a hypermedia type and XML knows nothing about hypertext.

smizell··on The lie of the API
The big benefit the author is describing comes from content negotiation and hypermedia types. The idea behind content negotiation is that a client and a server should decide and agree upon the media type that will be used in the communication without any human intervention (even a developer). This is accomplished with the Accept header, where the client tells the server, "Here are the media types that I understand." Most times, we developers use the Accept header as "Here is the media type I want you to send me." If we use the former, the server will figure out what media type to send based on the clients acceptances and preferences.

Here's the great thing about it. If APIs are built this way, and if clients are built to read and understand common and registered hypermedia types, there could be a time where clients and servers are able to communicate in such a way that the media type becomes seemingly invisible to the developer. We see this with the most popular REST client/server combo, the browser and the web server that serves up HTML. As the user, you can traverse the RESTful HTML API that websites have while the media type, HTML, is mostly concealed to the user. In other words, there is a chance that a good number of HTML websites are more RESTful than most of the APIs we see today.

In reducing REST to simply RPC over the web and skipping over the ideas of content negotiation and hypermedia types, we are missing out on the genius behind how the web was designed to be used. The author is really wanting us to go back to that instead of progressing toward the current patterns of fracturing your resources into separate APIs.

smizell··on The API wars are coming
What you're describing has already been done by SOAP+WSDL. Even the term "endpoint" is from the SOAP world, not the REST world. The IDE (usually) does all the heavy lifting of generating and consuming of these endpoints and the developers doesn't have to think about how endpoints are crafted.

REST is an architecture that can be implemented in many different ways, so I doubt there will ever be a one size fits all for REST. I think the real win will be when web frameworks allow us to work primarily with resources and representations instead of an MVC architecture.

smizell··on The API wars are coming
Doesn't true REST (not the RPC kind) address these same things when implemented? Content types and hypermedia to allow clients to know how to access the data and follow links to linked data?

If we all built our APIs with a registered content type, it would really go a long way for standardizing APIs. Throw in some HATEOAS and you've got standards and links.

smizell··on New API Commons Platform Allows Developers to Share APIs
I would say media types don't give you a full definition [1] because they really aren't meant to do so. They are meant to be used to express resources in a certain way that clients and servers can understand them.

Additionally, your resources should be described through link relations, which, along with media types, allow your API to be self describing and discoverable.

Take, for example, the Business API that is listed on the site [2] and picture Collection+JSON [3] being used to represent the business collection resource and the business item resource. If you used Collection+JSON, what would be left to describe? It would seem like you wouldn't need a Swagger file because your API would be describing itself.

Lastly, even though media types may not be actively promoted or used at this time, I think we should push toward promoting really good hypermedia types.

Edit: I wanted to also add a couple other interesting media types to check out, HAL [4] and Siren [5]. I'm sure there are other really good ones, too.

[1] By definition I'm taking it to mean fully describing an API.

[2] https://github.com/ongithub/businesses/blob/gh-pages/busines...

[3] http://amundsen.com/media-types/collection/

[4] http://stateless.co/hal_specification.html

[5] https://github.com/kevinswiber/siren

smizell··on New API Commons Platform Allows Developers to Share APIs
Hasn't this idea already been explored with registering media types? Isn't this what REST and all of the HTTP specs were meant to address? You use an existing hypermedia type or register a new one, then any client that can read those media types can read your API.

I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST.

As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward:

http://amundsen.com/blog/archives/1147

smizell··on Get information about any country via a RESTful API
Neither is more or less RESTful than the other. The media type and link relations express to the client what resource is being returned, not the URL itself.
smizell··on Get information about any country via a RESTful API
Just wanted to add some thoughts on how one could try to make this RESTful. First, if it were me, I'd pick a media type that can express hyperlinks in JSON (since JSON knows nothing about hyperlinks), maybe something like HAL [1]. Next, I would define my link relations for this API, which in this case would be a collection of countries and the countries themselves (so at least two different types of resources).

After creating the representations of each of these resources, I would then create URI templates in my root response (I guess found at /rest) that allow for the searching aspect that this site is providing, which would be something like:

  { 
    "_links": {
      "search_by_name": {
        "href": "/rest/name/{name}",
        "templated": true
      }
    }
  }
I may build on to this to provide other resources, like a collection of capitals, each with a link to "/rest/capital/{capital_city}", or a resource of currencies, linking to "/rest/currency/{currency}".

The goal of all of this would be to tell the client how to find resources rather than having that hard-coded into the client. These are just some first steps toward being RESTful, and there are lots of different directions you could take this and still be RESTful.

edit: example was incomplete

[1] http://stateless.co/hal_specification.html

smizell··on Best Practices for Designing a Pragmatic RESTful API
Isn't HATEOAS more about just URL changes, though? It is about letting the responses provide available responses to the client. This requires a commitment to creating media types or using existing ones, along with using link relations. Not using REST correctly leads to such complicated best practices that recommend adding .json to a URL to get the JSON representation. You shouldn't have to go to the documentation to figure out have to craft that URL to get a representation of a resource.
smizell··on Best Practices for Designing a Pragmatic RESTful API
I think we spend too much time trying to craft beautiful, descriptive URLs, where we should be spending our time crafting beautiful, descriptive responses. We try to make the URL describe to the developer what is being returned, when in reality, this should be dictated by media types and link relations.

Take for instance the example above. Whether the URL is /images/10/view or /images/10.png, the developer has no idea what kind of resource that is without any media types or relations (the file extension != to the media type). In other words, you could use both URLs to return the same exact resource, and the client shouldn't care. You could even change back and forth between those URLs and the client should never flinch.

This is actually a good example. Say you are serving a static PNG file at /images/10.png, linked in your server response (i.e. in some href like above). Say you want to change things up to do some type of logging on how many times the image has been viewed, so you write some code, create a response at /images/10/view, log views, and return the image with an image/png media type. You just did a really big API change and the client didn't have to be changed.

Now if your client was dumber, and was crafting URLs as /images/{id}.png, you would break all of your clients if you did the above changes. This of course is really just the tip of the iceberg of what flexibility HATEOAS can bring.

smizell··on Best Practices for Designing a Pragmatic RESTful API
I believe it's actually the other way around, where HATEOAS is the least "enterprisy" of the options. When I think of enterprise or over-complication, I think of a system where logic is so deeply embedded in the server and client that if the client or server changes in any way, everything breaks. REST was designed to better handle changes between a client and server. For instance, if you built your API to use something like Collection+JSON, then it could be instantly read and understood by any Collection+JSON client (much like in the way the HAL browser works [1]). You could change things, move things, even redo URLs, and the client will still work.

If, on the other hand, you don't conform and use HATEOAS, you have to go look at the documentation on how to build the URL to make a call to the API. Your client can never explore an API, but must be built to make certain calls to certain URLs that are built a certain way.

True REST with HATEOAS was what HTTP 1.1 was built around. It may take some extra work to implement, but it was designed to make communication over the web simpler (and it's worth the trouble). Unfortunately, this article is not really endorsing what REST is, but rather a very common RPC that has been popularized by Rails and labeled as REST.

[1] http://haltalk.herokuapp.com/explorer/browser.html#/

smizell··on RAML - RESTful API modeling language
I think the different definitions for REST have really muddied the water. To the REST purist, RAML is falling well short of being truly RESTful for reasons which you've mentioned. In other words, RAML isn't REST at all. To most others, REST is simply another RPC, like SOAP (hence all of the comments saying this is not much better than SOAP). Those of the latter thinking need someway to describe how their API should be consumed other than hypermedia types, so specs like RAML are born.

On their site, they say, "RAML isn't strict: in the end it is only describing HTTP with a few higher-level (optional) constructs." Looks like it's aiming to describe HTTP and URLs rather than hypermedia types.

smizell··on Webhooks, REST and the Open Web
Just above the diagram the author speaks about this:

"In addition to these operations, the subscription server may verify the intent of the subscriber by making an HTTP call to the provided callback with the same parameters requested before and an additional hub.challenge that must be echoed back by the subscriber."

← PreviousPage 2 of 2