Best Practices for Designing a Pragmatic RESTful API | Vinay Sahni. Your data model has started to stabilize and you're in a position to create a public API for your web app. You realize it's hard to make significant changes to your API once it's released and want to get as much right as possible up front. Now, the internet has no shortage on opinions on API design. But, since there's no one widely adopted standard that works in all cases, you're left with a bunch of choices: What formats should you accept? How should you authenticate? Should your API be versioned? In designing an API for Enchant (a Zendesk Alternative), I've tried to come up with pragmatic answers to these questions. My goal is for the Enchant API to be easy to use, easy to adopt and flexible enough to dogfood for our own user interfaces. ... or just skip to the bottom and signup for updates Key requirements for the API An API is a developer's UI - just like any UI, it's important to ensure the user's experience is thought out carefully!
Use RESTful URLs and actions Always use SSL. Caching. Build a Node API Client – Part 1: REST Principles. If you want developers to love your API, focus the bulk of your efforts on designing a beautiful one. If you want to boost adoption of your API, consider a tool to make life easier on your users: client libraries. Specifically, Node.js client libraries. This series will cover our playbook for building a stable, useful Node.js client in detail, in three parts: Part 1: Need-to-know RESTful Concepts Part 2: REST client design in Node.js Part 3: Functionality If you would like to learn general REST+JSON API design best practices, check out this video. Lastly, keep in mind that while these articles use Node.js, the same concepts apply to any other language client with only syntax differences.
OK. HATEOAS, usually pronounced ‘Haiti-ohs’, is an acronym for “Hypermedia As The Engine of Application State”. HATEOAS is still considered the ideal target for REST API design, but at times, HATEOAS will present a challenge to our REST client design efforts. REST Resources Collection Resources. What's the best way to write an API spec? There have been an explosion of API specification formats in the last few years. No clear winner has emerged. JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. API Blueprint is another emerging format for API description. Swagger is a YAML-based format for specifying JSON APIs. Slate is an API documentation framework/template, designed to generate very handsome documentation pages.
WADL is an API description language which describes API interactions in an XML format. Which of these is the best? Writing API Documentation with Slate. So you’ve built yourself an API. Perhaps it’s RESTful, RESTlike or something else entirely. You’ve implemented authentication – be it using OAuth, HTTP Basic Auth or JSON Web Tokens. You’ve fashioned your responses using JSON, maybe XML, or even something else. Your unit and integration tests are passing, you may have a third-party service such a Runscope testing it periodically, or using JSON or XML schemas to validate your responses. There’s one more thing, however. Thing is, an API is only as good as its documentation. There are a number of ways in which you can put together your documentation. You could of course hand-code it in HTML. Another option is Slate. What to Expect A picture speaks a thousand words; here’s an example, straight out-of-the-box: To see Slate-generated documentation in the wild, check out the Travis documentation, or Mozilla’s localForage or recroom docs.
Essentially, what you’ll get by default is the following: Getting Started Pre-requisites Installation For example: Rest - RESTful JSON API Documentation Generator. The 5 Functionalities Every API Must Have. When building a Web API, certain features are commonly needed for a baseline implementation. Sometimes these may be specific features built into the framework or they may need to be manually coded. In this post, I’ve compiled the various Node.js libraries, along with the key features, needed for API development. Regardless of API framework or language, the five functionalities outlined below are commonly an assumed part of the end product of the API service. 1.
Error handling When developing APIs for the Web, the standard approach is to return any errors with a respective HTTP code. 2. Once error handling is in place, errors often need to be logged so they can be reviewed. Libraries for error logging include log4js, bunyan, and winston. 3. Another common need is to validate the data that is coming into the API services being built. 4. Authentication and authorization happen in a number of different ways these days. One very well-known library is passport.js. 5.
Punch List: Engineering Blog. Today we’re open sourcing the toolchain Heroku uses to design, document, and consume our APIs. We hope this shows how Heroku thinks about APIs and gives you new tools to create your own APIs. This toolkit includes our HTTP API design guide, the prmd tool for managing JSON schemas and generating API docs, and client generators for Ruby and Go. Here’s some more information about these things, how we use them at Heroku, and an explanation of how you can try them yourself. HTTP API Design Guide The Heroku HTTP API Design Guide shows how we design and document APIs at Heroku. We use this guide to increase the consistency and quality of the APIs we deliver, both for our user-facing product and for internal services.
This document includes guidance on versioning, resource structure and attribute naming, serialization, errors handling, request ids, pagination, and caching support. This document is a work in progress. Schema and Documentation Toolchain For example: Usage at Heroku Summary. Pksunkara/alpaca. Angularjs - How to test endpoints protected by csrf in node.js/express. Protocol design - Efficient and stateless anti-forgery method - Cryptography Stack Exchange.
If you don't want to store the anti-CSRF tokens on the server, for most purposes it is sufficient to simply store the token as an HTTP cookie on the client. The OWASP wiki calls this technique "Double Submit Cookies". The reason this works is that, in the standard CSRF attack scenarios, the attacker cannot directly read or modify the user's cookies. Indeed, if the user's authentication credentials are also stored in cookies (as is very commonly done in modern web applications), any leak of cookie data already implies a much more fundamental security failure than a mere CSRF attack. Of course, an attacker might be able to gain (full or partial) access to the user's cookies via an XSS or other injection attack or through session fixation, but this is mostly outside the scope of CSRF prevention and must be addressed by other means. Let: When creating a form, calculate the anti-CSRF token T as T = \operatorname{MAC}_K([U, S, F, D])
Advanced CSRF and Stateless Anti-CSRF. OAuth 2.0 – The Good, The Bad & The Ugly. In a world dominated by social media, it's hard to not come across a client application which you have used to access restricted resources on some other server, for example, you might have used a web-based application (like NY Times) to share an interesting news article on your Facebook wall or tweet about it. Or, you might have used Quora's iPhone app that accesses your Facebook or Google+ profile and customizes the results based on your profile data, like suggesting to add/invite other users to Quora, based on your friends list. The question is, how do these applications gain access to your Facebook, Twitter or Google+ accounts and how are they able to access your confidential data?
Before they can do so, they must present some form of authentication credentials and authorization grants to the resource server. OAuth is often described as a valet key for the web. However, OAuth is not a new concept, but a standardization and combined wisdom of many well established protocols. 40 useful APIs for web designers and developers. An application programming interface (API) is a set of rules and specifications that software programs can follow to communicate or ‘interface’ with each other. As developers are well aware, there are hundreds of APIs out there for doing almost anything you could imagine online. Some are better than others, and some are definitely more useful than others. Below are forty of the most useful APIs out there.
The included APIs will let you do everything from shortening a URL to displaying a book preview on your site to interacting with your Twitter account, and everything in between. Please share with us which APIs have you found most useful and feel free to recommend others that we may have missed… The Google APIs Google offers dozens of APIs for web designers and developers. Some are specifically related to popular Google products, like Gmail and Analytics, while others are more specialized and aren’t part of public programs.
All are free to use, of course. The Yahoo! Like Google, Yahoo! Social Login Buttons Aren’t Worth It. I stumbled across a very disturbing number in our analytics earlier this year. From April 12 to May 12, 2012, we had 340,591 failed login attempts. That’s the total number of times someone tried to get into MailChimp to get their work done and couldn’t remember their username and/or password, or simply mistyped. Think of how much wasted time and frustration that translates to. It’s impossible to calculate, but let’s just say it’s a lot. Of the people who struggled logging in, 68,145 had to resort to resetting their password, and 38,137 had to get a reminder about their username. These numbers were depressing to the User Experience team.
These compelling stats and sound logic convinced us (and so many others) that adding social login buttons to our app were essential to improving our depressing failure rate. "I feel strongly about this. " I was blown away and dumbfounded by the value of social login buttons. I was, um, not super happy to get that email. The secret to our success. RESTful HTTP in practice. This article gives a short overview about the basics of RESTful HTTP and discusses typical issues that developers face when they design RESTful HTTP applications.
It shows how to apply the REST architecture style in practice. It describes commonly used approaches to name URIs, discusses how to interact with resources through the Uniform interface, when to use PUT or POST and how to support non-CRUD operations. REST is a style, not a standard. There is neither a REST RFC, nor a REST protocol specification nor something similar. Even though REST is heavily influenced by the Web-Technology, in theory the REST architecture style is not bound to HTTP. The idea behind RESTful HTTP is to use the existing features and capabilities of the WEB. Resources Resources are the key abstractions in REST. For instance, the classes, shown in Figure 1, could easily be mapped to such resources. Figure 1: Example analysis model The analysis model is a good starting point for identifying resources. Be careful when going client-only (Firebase) - Robin Verton - application security and web development.
Firebase, the scalable real-time backend Developing client-only applications with JavaScript and services like Firebase offer a nice way to “build apps without managing servers”. However, sometimes it’s not a bad idea to have some controlling server between your client and your data storage. When recently browsing over firebase.com and looking at one of their code examples to get a simple overview of their service, I was surprised how easy it is for clients to interact with the data storage/backend.
The code example I had a look at is a service to show “online presence” of users. Whenever a user visits the page, he is prompted for a name which is then saved in the data storage and therefore also send to all users which use this firebase reference (usually all users on a page would use the same reference so you can see all users which are currently online). Establishing a connection to the Firebase-Reference is a simple one-liner in Javascript: Four lines of code, 100 online users. Methods. Standard Methods We already discussed that resources are the fundamental concept in a RESTful API, and that each resource has its own unique URL.
Methods can be executed on resources via their URL. The table below lists the standard methods that have a well-defined meaning for all resources and collections. Normally, not all resources and collections implement all methods. There are two ways to find out which methods are accepted by a resource or collection. Use the OPTIONS method on the URL, and look at the “Allow” header that is returned. This header contains a comma-separated list of methods are are supported for the resource or collection.Just issue the method you want to issue, but be prepared for a “405 Method Not Allowed” response that indicates the method is not accepted for this resource or collection. Actions Sometimes, it is required to expose an operation in the API that inherently is non RESTful. PATCH vs PUT An additional method called PATCH has been proposed recently. ! ! So I wrote a JSON API Framework and the Framework was the Least Interesting Part « caines.ca.
Suggested Hacker News title: “Show HN: I’m only 37 and I wrote this over the weekend (plus the previous ~400 days)” First a little background I’ve always been a big fan of REST the way Roy intended it for two major reasons: It uses HTTP the way HTTP was intended, playing on its strengths and not wasting any time re-inventing what HTTP already has.The state of HTTP APIs these days is really ridiculously bad, given what we should have learned from the unfathomable success of the WWW. I was also envious as hell at the great framework Erlang developers had in Web Machine . If you write HTTP APIs for a living and you haven’t seen HTTP mapped to a state machine, you really owe it to yourself to check it out.
It’s brilliant. The thing I really wanted to do though was make web APIs not so terrible. If you rely on someone else’s API in your day-to-day work, you probably know what I mean. So the APIs I wanted to make and to use would be: Then I saw Jon Moore make it real with an XHTML API .