What about jsonrpc (http://json-rpc.org/)? I am using it in a project and I really appreciate the simplicity. Would be curious to hear from others who have experimented with it.
Designing a Pragmatic RESTful API
81–90 of 139 posts
Re: Designing a Pragmatic RESTful API
#82Don't limit yourself to JSON. Your dislike of XML does not mean that JSON is always the right answer. Instead, write code that flexibly can render to any of a set of formats, and use content negotiation to determine which format the user agent wishes to consume. This lets you do things like let the read-only portion of your API be accessible via browser, and it will future-proof you.
when he says "use JSON where possible XML only where you have to", I thought it was funny, like developers out there are just dying to use this verbose behemoth instead of its terser cousin json. But anyways, I agree with everything you're saying just wondering if there actually are any devs out there who just adore some sweet XML (seriously) ?
OP here. I got an email with an interesting argument on the topic. Paraphrasing: Today JSON is hip, tomorrow may be something else. By supporting XML by default and using XSLT to translate it to alternate outputs, you're able to support multiple formats without having to modify your software itself. Ofcourse, this does come with the cost of having to maintain XSLT files.
To businesses that need to support multiple formats (enterprise requirements?), XML + XSLT sounds like a fair approach - it allows you to simultaneously create idiomatic XML & JSON
Re: Designing a Pragmatic RESTful API
#83Question: in all discussion about API design, the hairiest to me is always authentication. The article recommends SSL, but the internet says that "SSL is slow." Is there a guide to using SSL correctly, and techniques for making this more efficient? An SSL primer? It also recommends using oauth. There are hundreds of libraries for consuming oauth APIs. What exists (I'm a Python+Flask guy, but really any help would be…
SSL is not slow. Grab the latest version of Nginx, turn on SPDY, enable SSL session cache. You must always serve your API over SSL, as auth information is going to be in headers or the querystring and both would be readable by a MITM if you do not use SSL. Nginx 1.4 statements to pay attention to (sample config): ssl on; ssl_certificate /etc/ssl/domain.crt; ssl_certificate_key /etc/ssl/domain.key; ssl_session_cache s…
Just to add: make sure your applications handle SSL certificates properly, and only trust either verified signed certificates or only the known certificate from the API server. Otherwise MITM could still expose everything.
Re: Designing a Pragmatic RESTful API
#84I am not sure I follow his point about why HATEOAS is not practical, but I know that I have been able to make it work in my own REST APIs using content types. I only return JSON if the Accept header specifies "application/json". (Which is probably what you should be doing anyhow.) I usually also allow an HTML fragment response for the "text/html-fragment" Accept type. The default response type (or if "text/html" is e…
Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.
Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) That's why it's not called JATEOAS. The information you are asking for sounds more appropriate in an OPTIONS request.
Re: Designing a Pragmatic RESTful API
#85Earlier quoted context omitted.
Huh, TIL. What was the reasoning behind this?
When client connects to server, first it does the SSL handshake. Then it sends HTTP headers. As a result, SSL really has nothing to do with HTTP and could be used to wrap other protocols. Check out stunnel ( https://www.stunnel.org/index.html ) which can be used to arbitrarily encrypt communications for any TCP based protocol
And one of the first parts of the SSL handshake is for the server to send the certificate to the client, so the server has to know which certificate to send based only on the IP address that the client is connecting to. The client then verifies that the certificate matches the host name it's trying to connect to. Then it sends the Host: header with the request.
It's a strict layering: TCP - SSL ("Secure Socket Layer", right?) - HTTP
There are two (and a half) ways of using a SSL certificate for multiple hostnames on the same IP address / interface: SNI (Server Name Identification (?)) and Subject Alt Names or Wildcard certificates. SNI extends the SSL protocol to send the hostname during the client handshake. The Subject Alt Name extension, which has been more reliable and available for me, adds multiple hostnames to the certificate for the client to match against. Wildcards do the same thing, patternistically: *.example.com.
Re: Designing a Pragmatic RESTful API
#86Great article. I'm actually in the middle of building out a new API. I've built many RESTful APIs but I'm starting to rethink of a couple of things with this new one. Does anyone have any good resources on when it's NOT appropriate to use REST? Or is the assumption that it should generally work for anything if you model it right? I ask this because the API I'm building is for a B2B product and lot of the "actions" ar…
> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don'…
I can think of an example:
Send a message to the server to process all approved cases, which has no connection to an individual resource. The client has no fundamental knowledge of all server-side resources that may or may not be affected, and may not even be allowed that information.
It's an action, but it's not really a post. You're not creating a new resource. You're not patching anything, you're not really getting anything... It's closest to a PUT, but you're not really updating a particular resource...
This may not be a document-based API like REST expects, but it is a fairly common enterprise requirement for a system.
Re: Designing a Pragmatic RESTful API
#87Earlier quoted context omitted.
While we're dispelling SSL myths, let me add the reminder that SSL does encrypt the URL and querystring and HTTP headers. It doesn't look like it in browsers because they still show the URL cleartext onscreen, but over the wire all of that is indeed inside the encryption envelope. Only the destination IP address isn't encrypted.
And whilst we're still here... SNI and SSL. Thanks to Internet Explorer, and the early versions of the stock browser on Android, you will need a unique IPv4 address for your SSL endpoint. You cannot safely serve multiple SSL sites on the same IP.✝ Basically: The hostname is also encrypted, so the SSL requests on some browsers require a unique IPv4 address. Your provider will give you one if you say the magic word "SS…
Internet Explorer does support SNI since IE7. However Windows XP doesn't even if running IE7 or newer.
That said, we're on our way to a bright SNI filled future, we just have to get over the hump of old versions of Windows and some old mobile devices before it's common enough to be used reliably.
Re: Designing a Pragmatic RESTful API
#88Earlier quoted context omitted.
Use an expiring token like mechanism. The API user first gets a token using credentials. Future requests use the token for authentication. A new token will be required periodically.
What are the benefits of doing this instead of just requiring authentication with every request? Is it because the authentication part is a lot of work for the server or client? Is it for the negligible (in this context) security benefits of not using the same secret-key for all traffic?
The hashing for the authentication is intentionally computationally slow (thus mitigating brute force validation). The token issued is basically like a session id - validating a session id is really just like string compare, so it's much much fast.
Re: Designing a Pragmatic RESTful API
#89We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article. The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. I've built a couple of very pure R…
The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs http://…
There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation.
Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty applications.
The only thing that bothers me, though, is when these RPC APIs are called "RESTful" just because they use HTTP verbs correctly.
Re: Designing a Pragmatic RESTful API
#90Earlier quoted context omitted.
> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don'…
I can think of an example: Send a message to the server to process all approved cases, which has no connection to an individual resource. The client has no fundamental knowledge of all server-side resources that may or may not be affected, and may not even be allowed that information. It's an action, but it's not really a post. You're not creating a new resource. You're not patching anything, you're not really gettin…
> Send a message to the server to process all approved cases, which has no connection to an individual resource.
"Individual resources" are defined by the needs of the API. If you need an endpoint that can be given a command to process all approved cases, then that is an "individual resource".
The particular kind of resource I'd normally model it as is one which is or has a collection resource in which individual command instances are the members of the collection.
> It's an action, but it's not really a post.
I disagree. Submitting a new request to initiate the action is exactly a request to create a new command resource subordinate to the collection of commands subordinate to the command processing endpoint resource, which naturally maps to an HTTP POST action to the collection. The processing of approved cases, and the resulting changes to the backend data store, are consequences (side effects) of the creation of that resource.
> This may not be a document-based API like REST expects
REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents".