How to Expose User Information

3 Replies

At a first glance you might think that offering an API method that returns information about your application users might not be a good idea. With the increasing usage of APIs for business related purposes you might fear that you’re giving away precious information about your customers.

photo by The Wide Wide World

But think again. If you give the right amount of information, applications built on top of your API will be able to offer a better service to your users. Your final user will have a better experience and that might turn out to generate more business for you.

Continue reading “How to Expose User Information” »

An Overview of REST Metadata Formats

10 Replies

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!).

Criminals

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