Tag Archives: API

URL Design for RESTful Web Services

URL design discussions for RESTful web services often degrade into debates over pluralization and parameter names. There are a couple of principles I like to use to keep things simple.

1) Using your API should feel like using a filesystem

Endpoints used to create, list, and search for entities should look like directories, e.g. /users
Use a plural noun so it feels like a directory of users, not a user controller
Endpoints used to read, update, and delete individual entities should look like files, e.g. /users/charlie

Continue reading “URL Design for RESTful Web Services” »

How safe is your API from its users?

3 Replies

Availability and safety are some of the most important implicit factors to the user experience of your platform’s users. When we discuss web security to ensure these factors, images of criminal rings using sophisticated techniques come to mind. Even if your data seems too low of worth for this scenario, perhaps the over-caffeinated, zit-faced script kiddie wreaking havoc on your operations is a fear.

However, the all-too-common reality in the API world is that your worst enemies are often your worst customers. Irresponsible or unknowledgeable developers writing super chatty apps. Opportunistic partners who look to take advantage of data that gives them value, in the form of high volume traffic, and no value for you in return. Scarier yet are users whose security tokens are compromised, leaving everything from users’ personal information to financial transactions at risk (now we might be talking about criminals again!).

Continue reading “How safe is your API from its users?” »

2 steps to better API Error Codes

14 Replies

One of the biggest difficulties developers can have when writing code that talks with an API is dealing with errors and exceptions, and translating those errors into something meaningful for their applications.

photo by Bent Jensen

Because APIs are based on different technologies and libraries, error codes are often inherited and do not make sense to whatever framework the consumer is using. Even worse is when those error codes and messages are simply passed through to the end-user without any manipulation by the application.

So, how can you make sure that all your API consumer understand your error codes and can handle them properly? If you’re offering a REST API, consumers expect your endpoints to behave like any other HTTP endpoint, so a good start is to simply follow the standards.

Continue reading “2 steps to better API Error Codes” »

Is end-user API UX a Utopia?

1 Reply

I have been working as a User Experience designer at CloudWork for the past 6 months and I’ve faced many challenges and opportunities while building an easy to use product that automates business processes and synchronizes cloud-based applications.

The UI and UX of the application was very easy to create compared to the actual UX of the service. The uncertainty and the number of dependencies for creating a successful integration between cloud applications is so high that it seems almost impossible to guarantee the Quality of Service.

The main issue is the lack of standards. Each application has a different API, different logic, different nomenclature. Even applications of the same class, e.g. CRM, are completely different beasts. This makes it really hard to guarantee the same solid integration between CRM A and APP X compared to CRM B and APP X. This can make creating a consistent User Experience very difficult.

Continue reading “Is end-user API UX a Utopia?” »

Authentication: Don’t be Clever

14 Replies

HTTP API authentication has evolved through many forms over the years. As so-called RESTful APIs gained popularity, a variety of methods sprung up: key passing, plain-old HTTP Basic Auth, OAuth 1.0, OAuth 1.0a, OAuth 2.0 (and it’s 40 revision) and some less-common custom schemes. With the OAuth 2.0 specification finalized, things are finally starting to settle down and coalesce around a single auth mechanism. For publicly-available APIs, OAuth 2.0 should be on your list of requirements.

Continue reading “Authentication: Don’t be Clever” »