Is an API endpoint the &#39;method&#39;, like https://api.foursquare.com/v2/venues/ or the full URL including non-query-string parameters like  https://api.foursquare.com/v2/venues/5104

In other words, are these two separate endpoints or considered the same endpoint?
http://myapi.com/somemodel/1  
http://myapi.com/somemodel/2


API Endpoint Semantics

I had a look at https://stackoverflow.com/questions/389169/best-practices-for-api-versioning, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am having two URIs (one with versioning as part of the URI and one without):

    http://xxxx/v1/user/123    -&gt; favored solution in discussed thread
    http://xxxx/user/123             

I am having my doubts whether the first link expresses the idea of REST. I find `http://xxxx/v1/user/123` confusing as it suggests that there will be a higher api-version someday like `http://xxxx/v2/user/123`. But this does not make sense in REST terms, the api version itself is HTTP 1.0 or 1.1, which is already sent inside the HTTP request. This REST resource centric view differs very from other api-interfaces like SOAP or Java-interfaces (where it is common to have api-versions in qualified names).


At REST the only thing where versioning makes sense is the representation of that resource (e.g. new fields are added or removed). This versioning belongs to the part of content-negotiation like:

    http://xxx/user/123 + HTTP &#39;Accept&#39; Header -&gt; Content negotation through header
    http://xxx/user/123?v=1                    -&gt; for perma-links/hyperlinks


One could also argue that such version content-negotiation could be part of the URI inside the path, but I find it counter-intuitive, because you could end-up with different URIs for the same resource and have to maintain redirects at some point.

To sum-up: In REST URIs there is no api-versioning, only versioning of the resource&#39;s representation. Representation version-info belongs to content-negotiation (as queryParam or HTTP &#39;Accept&#39;).

What do you think? In which things would you disagree/agree?


REST api versioning (only version the representation, not the resource itself)

I&#39;m designing an API with SQLAlchemy (querying MySQL) and I would like to force all my queries to have page_size (LIMIT) and page_number (OFFSET) parameters.

Is there a clean way of doing this with SQLAlchemy?  Perhaps building a factory of some sort to create a custom Query object?  Or maybe there is a good way to do this with a mixin class?

I tried the obvious thing and it didn&#39;t work because .limit() and .offset() must be called after all filter conditions have been applied:

    def q(page=0, page_size=None):
        q = session.query(...)
        if page_size: q = q.limit(page_size)
        if page: q = q.offset(page*page_size)
        return q

When I try using this, I get the exception:

    sqlalchemy.exc.InvalidRequestError: Query.filter() being called on a Query which already has LIMIT or OFFSET applied. To modify the row-limited results of a  Query, call from_self() first.  Otherwise, call filter() before limit() or offset() are applied.


Applying LIMIT and OFFSET to all queries in SQLAlchemy

Unlike C#&#39;s `IEnumerable`, where an execution pipeline can be executed as many times as we want, in Java a stream can be &#39;iterated&#39; only once. 

Any call to a terminal operation closes the stream, rendering it unusable.
This &#39;feature&#39; takes away a lot of power. 

I imagine the reason for this is *not* technical. What were the design considerations behind this strange restriction?

Edit: in order to demonstrate what I am talking about, consider the following implementation of Quick-Sort in C#:

    IEnumerable&lt;int&gt; QuickSort(IEnumerable&lt;int&gt; ints)
    {
      if (!ints.Any()) {
        return Enumerable.Empty&lt;int&gt;();
      }
    
      int pivot = ints.First();
    
      IEnumerable&lt;int&gt; lt = ints.Where(i =&gt; i &lt; pivot);
      IEnumerable&lt;int&gt; gt = ints.Where(i =&gt; i &gt; pivot);
    
      return QuickSort(lt).Concat(new int[] { pivot }).Concat(QuickSort(gt));
    }

Now to be sure, I am not advocating that this is a good implementation of quick sort! It is however great example of the expressive power of lambda expression combined with stream operation. 

And it can&#39;t be done in Java!
I can&#39;t even ask a stream whether it is empty without rendering it unusable. 

Why are Java Streams once-off?

Keep in mind I have a rudimentary understanding of REST. Let&#39;s say I have this URL:

    http://api.animals.com/v1/dogs/1/

And now, I want to make the server make the dog bark. Only the server knows how to do this. Let&#39;s say I want to have it run on a CRON job that makes the dog bark every 10 minutes for the rest of eternity. What does that call look like? I kind of want to do this:

URL request:
    
    ACTION http://api.animals.com/v1/dogs/1/

In the request body:

    {&quot;action&quot;:&quot;bark&quot;}

Before you get mad at me for making up my own HTTP method, help me out and give me a better idea on how I should invoke a server-side method in a RESTful way. :)

**EDIT FOR CLARIFICATION**

Some more clarification around what the &quot;bark&quot; method does. Here are some options that may result in differently structured API calls:

1. bark just sends an email to dog.email and records nothing.
2. bark sends an email to dog.email and the increments dog.barkCount by 1.
3. bark creates a new &quot;bark&quot; record with bark.timestamp recording when the bark occured. It also increments dog.barkCount by 1.
4. bark runs a system command to pull the latest version of the dog code down from Github. It then sends a text message to dog.owner telling them that the new dog code is in production.

Call a Server-side Method on a Resource in a RESTful Way

What is the REST-ful way of deleting multiple items?

My use case is that I have a Backbone Collection wherein I need to be able to delete multiple items at once. The options seem to be:

1. Send a DELETE request for every single record (which seems like a bad idea if there are potentially dozens of items);
2. Send a DELETE where the ID&#39;s to delete are strung together in the URL (i.e., &quot;/records/1;2;3&quot;);
3. In a non-REST way, send a custom JSON object containing the ID&#39;s marked for deletion.

All options are less than ideal.

This seems like a gray area of the REST convention.

Delete multiple records using REST

according to the documentation, the method [`String.valueOf(Object obj)`][1] returns:

&gt; if the argument is `null`, then a string equal to `&quot;null&quot;`; otherwise, the value of `obj.toString()` is returned.

But how come when I try do this:

	System.out.println(&quot;String.valueOf(null) = &quot; + String.valueOf(null));

it throws NPE instead? (try it yourself if you don&#39;t believe!)

&lt;pre&gt;
    Exception in thread &quot;main&quot; java.lang.NullPointerException
	at java.lang.String.&lt;init&gt;(Unknown Source)
	at java.lang.String.valueOf(Unknown Source)
&lt;/pre&gt;

How come this is happening? Is the documentation lying to me? Is this a major bug in Java?


  [1]: http://java.sun.com/javase/6/docs/api/java/lang/String.html#valueOf(java.lang.Object)

Why does String.valueOf(null) throw a NullPointerException?

The following code throws `NullPointerException`:

    int num = Integer.getInteger(&quot;123&quot;);

Is my compiler invoking `getInteger` on null since it&#39;s static? That doesn&#39;t make any sense!

What&#39;s happening?

Why does int num = Integer.getInteger(&quot;123&quot;) throw NullPointerException?

If you have an API, and you are a UK-based developer with a highly international audience, should your API be 

    setColour()

or

    setColor()

(To take one word as a simple example.)

UK-based engineers are often quite defensive about their &#39;correct&#39; spellings but it could be argued that US spelling is more &#39;standard&#39; in the international market.

I guess the question is does it matter? Do developers in other locales struggle with GB spelling, or is it normally quite apparent what things mean?

Should it all be US-English?

GB English, or US English?

I&#39;ve got a JSON REST API. There is a handshake that will give you a token that is valid for 15 minutes. All calls you do within those 15 minutes should work ok. After the 15 minutes I am returning an error object (includes code, message, success = false) but I was also wondering what HTTP Error Code I should return? And will using a HTTP error code mess up certain clients? (HTML5, iPhone, Android). What is considered best practice in this scenario?

Token Expired - JSON REST API - Error Code

For example you run a GET request for `users/9` but there is no user with id #9.
Which is the best response code?

 - 200 OK
 - 202 Accepted
 - 204 No Content
 - 400 Bad Request
 - 404 Not Found

What is the proper REST response code for a valid request but an empty data?

As far as I can tell each individual resource should have **only one canonical** path.  So in the following example what would good URL patterns be?

Take for example a rest representation of Companies. In this hypothetical example, each company **owns** 0 or more departments and each department **owns** 0 or more employees. 

A department **can&#39;t exist** without an associated company. 

An employee **can&#39;t exist** without an associated department.

Now I&#39;d find the natural representation of the resource patterns to be. 

* `/companies` *A collection of companies* - Accepts POST for a new company. Get for the entire collection.
* `/companies/{companyId}` An individual company. Accepts GET, PUT and DELETE
* `/companies/{companyId}/departments` Accepts POST for a new item. (Creates a department within the company.)
* `/companies/{companyId}/departments/{departmentId}/`
* `/companies/{companyId}/departments/{departmentId}/employees`
* `/companies/{companyId}/departments/{departmentId}/employees/{empId}`

Given the constraints, in each of the sections, I feel that this makes sense if a bit deeply nested.

However, my difficulty comes if I want to list (`GET`) all employees across all companies.

The resource pattern for that would most closely map to `/employees` (The collection of all employees)

Does that mean that I should have `/employees/{empId}` also because if so then there are two URI&#39;s to get the same resource?

Or maybe the entire schema should be flattened but that would mean that employees are a nested top-level object.

At a basic level `/employees/?company={companyId}&amp;department={deptId}` returns the exact same view of employees as the most deeply nested pattern.

What&#39;s the best practice for URL patterns where resources are **owned** by other resources but should be query-able separately? 


What are best practices for REST nested resources?

When designing resource hierarchies, when should one use sub-resources?

I used to believe that when a resource could not exist without another, it should be represented as its sub-resource. I recently ran across this counter-example:

* An employee is uniquely identifiable across all companies.
* An employee&#39;s access control and life-cycle depend on the company.

I modeled this as: `/companies/{companyName}/employee/{employeeId}`

Notice, I don&#39;t need to look up the company in order to locate the employee, so should I? If I do, I&#39;m paying a price to look up information I don&#39;t need. If I don&#39;t, this URL mistakenly returns HTTP 200:

`/companies/{nonExistingName}/employee/{existingId}`

1. How should I represent the fact that a resource to *belongs* to another?
2. How should I represent the fact that a resource *cannot be identified* without another?
3. What relationships are sub-resources meant and not meant to model?

RESTful design: when to use sub-resources?

### Background:
I am taking a class at my university called &quot;Software Constraints&quot;. In the first lectures we were learning how to build good APIs. 

A good example we got of a really bad API function is the socket `public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);` in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the `Select()`. It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +/-35 minutes (because it is an int).

---
### Questions:

 1. How do you define an API as
    &#39;bad&#39;?   
 2. How do you define an
    API as &#39;good&#39;?

---
### Points to consider:
 - Function names that are hard to remember.
 - Function parameters that are hard to understand.
 - Bad documentation.
 - Everything being so interconnected that if you need to change 1 line of code you will actually need to change hundreds of lines in other places.
 - Functions that destroy their arguments.
 - Bad scalability due to &quot;hidden&quot; complexity.
 - It&#39;s required from the user/dev to build wrappers around the API so that it can be used.



How do you define a good or bad API?

As most people are painfully aware of by now, the Java API for handling calendar dates (specifically the classes `java.util.Date` and `java.util.Calendar`) are a terrible mess.

Off the top of my head:

 - Date is mutable
 - Date represents a timestamp, not a date
 - no easy way to convert between date components (day, month, year...) and Date
 - Calendar is clunky to use, and tries to combine different calendar systems into one class

[This post][1] sums it up quite well, and [JSR-310][2] also expains these problems.

Now my question is: 

How did these classes make it into the Java SDK? Most of these problems seem fairly obvious (especially Date being mutable) and should have been easy to avoid. So how did it happen? Time pressure? Or are the problems obvious in retrospect only?

I realize this is not strictly a programming question, but I&#39;d find it interesting to understand how API design could go so wrong. After all, mistakes are always a good learning opportunity (and I&#39;m curious).


  [1]: http://www.jroller.com/cpurdy/entry/the_seven_habits_of_highly
  [2]: http://jcp.org/en/jsr/detail?id=310

Why is the Java date API (java.util.Date, .Calendar) such a mess?

The [wikipedia article][1] about [Law of Demeter][3] says:
&gt; The law can be stated simply as &quot;use only one dot&quot;.

However a [simple example][4] of a [fluent interface][2] may look like this:

    static void Main(string[] args)
    {
       new ZRLabs.Yael.Pipeline(&quot;cat.jpg&quot;)
            .Rotate(90)
            .Watermark(&quot;Monkey&quot;)
            .RoundCorners(100, Color.Bisque)
            .Save(&quot;test.png&quot;);
    }

So does this goes together?

  [1]: http://en.wikipedia.org/wiki/Law_Of_Demeter
  [2]: http://en.wikipedia.org/wiki/Fluent_interface
  [3]: http://c2.com/cgi/wiki?LawOfDemeter
  [4]: http://weblogs.asp.net/jgalloway/archive/2006/12/06/a-simple-example-of-a-fluent-interface.aspx

Do fluent interfaces violate the Law of Demeter?

Seems like there are two categories of APIs for websites today.  

1.  APIs which allow the functionality of the site to be extended like Facebook, Myspace, etc.  These APIs seem to be very diverse.

2.  APIs which allow interaction with the existing site functionality like Twitter, Flickr, etc.  These all claim to be REST based, but are in reality simply &quot;data over HTTP&quot;.

If you were creating a website that allowed both functional extension and outside interaction, what existing APIs would you use as a reference model?
   





What is the gold standard for website APIs?  Twitter, Flickr, Facebook, etc

I was looking at the [Duration][1] class in Java 8 and noticed that it does not have:

    long toSeconds();

But it has all other `toXXXXX()` to get days, hours, minutes, millis, nanos.  I do see a `getSeconds()` method that returns the number of seconds within this duration object.  There is also a `get(TemporalUnit unit)` method to get the duration as the requested time unit.  But why not keep the `toSeconds()` method for consistency?


  [1]: https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html

Why does the Duration class not have &#39;toSeconds()&#39; method?

I want to make my RESTful API very predictable. What is the best practice for deciding when to make a segmentation of data using the URI rather than by using query params.

It makes sense to me that system parameters that support pagination, sorting, and grouping be after the &#39;?&#39; But what about fields like &#39;status&#39; and &#39;region&#39; or other attributes that segment your collection? If those are to be query params as well, what is the rule of thumb on knowing when to use path params? 




When do I use path params vs. query params in a RESTful API?

I&#39;d love some some help handling a strange edge case with a paginated API I&#39;m building.

Like many APIs, this one paginates large results. If you query /foos, you&#39;ll get 100 results (i.e. foo #1-100), and a link to /foos?page=2 which should return foo #101-200.

Unfortunately, if foo #10 is deleted from the data set before the API consumer makes the next query, /foos?page=2 will offset by 100 and return foos #102-201.

This is a problem for API consumers who are trying to pull all foos - they will not receive foo #101.

What&#39;s the best practice to handle this? We&#39;d like to make it as lightweight as possible (i.e. avoiding handling sessions for API requests). Examples from other APIs would be greatly appreciated!

API pagination best practices

I want to create a REST API for a file upload service that allows a user to:

  1. Open a session
  2. Upload a bunch of files
  3. Close the session

And then later, come back and do things with the files they uploaded in a previous session.

To facilitate dealing with data about each file and dealing with the content of the file itself, this is the URI scheme I am thinking of using:

    /sessions/
    /sessions/3
    /sessions/3/files
    /sessions/3/files/5
    /sessions/3/file/5/content
    /sessions/3/file/5/metadata

This will allow the file metadata to be dealt with separately from the file content. In this case, only a GET is allowed on the file _content_ and file _metadata_, and to update either one, a new file has to be PUT.

Does this make sense? If not, why and how could it be better?

All Api Design Solutions on Gang of Coders

Total of 21 Api Design Solutions