41

I have a RESTful API within a web-service with resources such as users, posts and so on. When I make a request for a list of posts (GET /posts), I want to retrieve an array of posts only with limited data for each post (i.e. subject, author name). When I make a request for a concrete post (GET /posts/42) I want to retrieve the full list of post object fields, including big post body, additional info about likes count, comments count. I suppose there exist many ways to solve this problem.
In my mind, the three most obvious are:

  1. Explicitly specify a fields list on every request (/posts?fields=subject,author_name and /posts/42?fields=subject,body,createAt,author_name,comments_count,likes_count, etc...).
  2. Explicitly specify a fields list only if it differs from the default fields list.
  3. Specify a fields list that should be excluded (or included) from (to) the default fields set if the desired fields set differs from the default.

I want to build a clear and useful API for my customers. Which way should I choose?

2 Answers 2

50

I'd go for option 2 IMHO.

So if the consumer just requests the resource url (/posts/42) they receive the default fields.

Then consumers can alter the default response by defining values in the query string like:

/posts/42/fields?subject,author_name

This has worked well for me in the past and is how some other well know APIs work, e.g. Facebook

Edit: Looking back at this I’d change the request to be:

/posts/42?fields=subject,author_name

/post/42 is the resource, not fields.

2
  • I'd agree. It provides a low barrier to entry, so developers can explore and can easily see the default fields, but still gives the flexibility to ask for exactly what you want if you need to.
    – theon
    Aug 14, 2013 at 21:25
  • I do option (2) also, but I allow fields=* to get all fields so that querying the full set is easy to do (esp. for a developer wanting to know or double check what that set is). May 6, 2014 at 22:16
13

Have been doing research into this as well and was pointed towards Facebook's GraphQL as an alternative to requesting a restful api with the fields wanted. It is still in the very early stages but seems very promising.

https://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html

EDIT: Reproduced from the URL:

A GraphQL query is a string interpreted by a server that returns data in a specified format. Here is an example query:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50)  {
      uri,
      width,
      height
    }
  }
}

(Note: this syntax is slightly different from previous GraphQL examples. We've recently been making improvements to the language.)

And here is the response to that query.

{
  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}
0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.