Databases
StackOverflow2013
Postsdbo
PO
 

Note that there are some explanatory texts on larger screens.

plurals
  1. PO
    primarykey
    data
    text
    <p>The URL should NOT contain the versions. The version has nothing to do with "idea" of the resource you are requesting. You should try to think of the URL as being a path to the concept you would like - not how you want the item returned. The version dictates the representation of the object, not the concept of the object. As other posters have said, you should be specifying the format (including version) in the request header.</p> <p>If you look at the full HTTP request for the URLs which have versions, it looks like this:</p> <pre><code>(BAD WAY TO DO IT): http://company.com/api/v3.0/customer/123 ====&gt; GET v3.0/customer/123 HTTP/1.1 Accept: application/xml &lt;==== HTTP/1.1 200 OK Content-Type: application/xml &lt;customer version="3.0"&gt; &lt;name&gt;Neil Armstrong&lt;/name&gt; &lt;/customer&gt; </code></pre> <p>The header contains the line which contains the representation you are asking for ("Accept: application/xml"). That is where the version should go. Everyone seems to gloss over the fact that you may want the same thing in different formats and that the client should be able ask for what it wants. In the above example, the client is asking for <i>ANY</i> XML representation of the resource - not really the true representation of what it wants. The server could, in theory, return something completely unrelated to the request as long as it was XML and it would have to be parsed to realize it is wrong.</p> <p>A better way is:</p> <pre><code>(GOOD WAY TO DO IT) http://company.com/api/customer/123 ===&gt; GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+xml &lt;=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+xml &lt;customer&gt; &lt;name&gt;Neil Armstrong&lt;/name&gt; &lt;/customer&gt; </code></pre> <p>Further, lets say the clients think the XML is too verbose and now they want JSON instead. In the other examples you would have to have a new URL for the same customer, so you would end up with:</p> <pre><code>(BAD) http://company.com/api/JSONv3.0/customers/123 or http://company.com/api/v3.0/customers/123?format="JSON" </code></pre> <p>(or something similar). When in fact, every HTTP requests contains the format you are looking for:</p> <pre><code>(GOOD WAY TO DO IT) ===&gt; GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+json &lt;=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+json {"customer": {"name":"Neil Armstrong"} } </code></pre> <p>Using this method, you have much more freedom in design and are actually adhering to the original idea of REST. You can change versions without disrupting clients, or incrementally change clients as the APIs are changed. If you choose to stop supporting a representation, you can respond to the requests with HTTP status code or custom codes. The client can also verify the response is in the correct format, and validate the XML.</p> <p>There are many other advantages and I discuss some of them here on my blog: <a href="http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html">http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html</a></p> <p>One last example to show how putting the version in the URL is bad. Lets say you want some piece of information inside the object, and you have versioned your various objects (customers are v3.0, orders are v2.0, and shipto object is v4.2). Here is the nasty URL you must supply in the client:</p> <pre><code>(Another reason why version in the URL sucks) http://company.com/api/v3.0/customer/123/v2.0/orders/4321/ </code></pre>
    singulars
    1. This table or related slice is empty.
    1. POBest practices for API versioning?
      singulars
      1. PTQuestion
    1. PTAnswer
    1. This table or related slice is empty.
    1. USjeremyh
    plurals
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    2. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    3. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    1. COHandling independent data contract version and service contract versions in Accept header seems a messy as much as it is messy in the URL. Are there any other options ? Also if I have multiple endpoints (soap, rest), should this also be indicated in Accepts and let the routing service at the server end decide the direction to the correct endpoint OR is it acceptable to have the endpoint coded in the URL ?
      singulars
      1. PO
      1. USideafountain
    2. COhttp://company.com/api/v3.0/customer/123/v2.0/orders/4321 drove your explanation home. Good example!
      singulars
      1. PO
      1. USJoe
    3. COI think this depends on the use-case. Working on internal company systems, Webservice versioning is required so that other internal systems (clients of the webservice) are given time to upgrade to the newest version. So the old version can be supported for a set time period (say only 1 month) and then turned off. In this case there doesn't seem to be an issue for me in having the version in the URL.
      singulars
      1. PO
      1. USjasop
 

Querying!

 
Guidance
A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload