Category Archives: Opinion

An Overview of REST Metadata Formats

Although the REST community initially took a stance against metadata for REST APIs, a number of metadata standards have none-the-less emerged over the last couple of years, mainly fueled by the need to document APIs for their consumers.

photo by CCAC North Library

As an added benefit, the same metadata is now often used to generate code (both client and server), create test harnesses, production monitors and perform real-time validation of request and response messages (when applicable). All of these provide a foundation for an improved Quality of Service (QoS) that many enterprises require as they adopt REST for their information architectures.

Continue reading “An Overview of REST Metadata Formats” »

URL Design for RESTful Web Services

12 Replies

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?” »