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.

Here are some guidelines on what should and shouldn’t be exposed and how you should offer the information through the API.

Personal information

There’s nothing wrong in exposing some personal information that might improve the user experience without leaking any compromising data:

• username: the nickname used when signing in, which might be useful to help the users quickly identify their accounts;
• first and last name: this will make the user experience more pleasant when using third-party applications;
• language: if you offer different languages you should expose this information so that the consumer application can better adapt its UI;
  
• timezone: when showing dates and times, it’s better to use the correct user’s timezone;
• country: if it makes sense, provide this information so that applications can decide what information to display and how to interact with the user.

Here’s a list of fields that you should definitely not expose through your API:

• e-mail address: if the consumer application is not controlled by you, they might easily spam users if they have their e-mail addresses;
  
• mailing address and phone number: likewise, exposing this information might potentially enable a third-party to spam your users;
• other sensitive information: whatever information you get from your users that shouldn’t be available to a third-party.

Billing information

You should be much more careful with this type of data, specially if you want to keep full control over how your customers are billed. Nevertheless, there’s some information that might be interesting to expose:

• plan name: if you offer multiple plans you can expose the name of the plan so that API consumers can adapt accordingly;
• plan features: any information that you display publicly on your Web site can also be exposed through the API (e.g. plan period, limitations, etc.).

In my opinion, any other billing information should be concealed from third-party applications that use your API.

API endpoint

The best way to expose user information, if your offering a RESTful API, is to have a dedicated endpoint that immediately returns all the available information about the current authenticated user, e.g. /users/me. Using me makes sense in this case because you’re returning information about the user (me, from her point of view).

Here’s an example of a possible JSON response to the user information endpoint:

HTTP/1.1 200 OK
Content-Type: text/json
{
    "username" : "johndoe",
    "firstName" : "John",
    "lastName" : "Doe",
    "language" : "en_US",
    "timezone" : "PDT",
    "country" : "United States",
    "plan" : {
        "name" : "Premium",
        "posts" : 10,
        "comments" : false
    }
}

Conclusion

Expose user information through your API so that third-party applications can offer users a better User Experience but be careful about sensitive data. Specifically, don’t make billing information public because it might let a third-party gain control over your customers.

Last updated by Bruno Pedro at April 12, 2013.