Introduction to RESTful Architecture

http://jeremyneiman.com/rest

Why?

A standard format to make it easy for other computers (client programs) to navigate and interact with your API

*Not a RESTful API. Not even close.

The Datasets

http://www.mta.info/developers/download.html

Subway/Bus/Train Schedules

Zip archives of .txt files containing CSV formatted data

Performance Data

Zip archives of .xml files containing XML formatted data

Service Status

.txt file containing XML formatted data

Elevator/Escalator Status

.xml file containing XML formated data

Fare Data

Web page listing of .csv files containing CSV formatted data.

etc.

rand()

Lesson 1

Consistency

Lesson 2

Accessibility

Let's take a peek at one of them, shall we?

Service Status is probably the most important piece of data if you're building a subway app.

<line>
<name>NQR</name>
<status>SERVICE CHANGE</status>
<text>
&lt;span class="TitleServiceChange" &gt;Service Change&lt;/span&gt;
&lt;span class="DateStyle"&gt;
&amp;nbsp;Posted:&amp;nbsp;04/22/2012&amp;nbsp; 1:50PM
&lt;/span&gt;
&lt;br/&gt;
&lt;br/&gt;
&lt;P&gt;Due to a signal problem at the &lt;STRONG&gt;Coney Island-Stillwell Avenue Station&lt;/STRONG&gt;, downtown [N] trains are terminating at the &lt;STRONG&gt;Bay Parkway Station&lt;/STRONG&gt; on the [D] line.&lt;/P&gt;
&lt;P&gt;For service between the &lt;STRONG&gt;Bay Parkway Station&lt;/STRONG&gt; and the &lt;STRONG&gt;Coney Island-Stillwell Avenue Station&lt;/STRONG&gt;, customers are advised to transfer to a Coney Island-bound [D] train at the &lt;STRONG&gt;Bay Parkway Station&lt;/STRONG&gt;.&lt;/P&gt;
&lt;P&gt;Please expect delays in [N] train service at this time.&lt;/P&gt;
&lt;br/&gt;
&lt;br/&gt;

&lt;span class="TitlePlannedWork" &gt;Planned Work&lt;/span&gt;
&lt;br/&gt;
&lt;HTML&gt;&lt;BODY&gt;&lt;a class="plannedWorkDetailLink" onclick=ShowHide(36886);&gt;
&lt;b&gt;[N] Coney Island-bound trains run via the [D] from 36 St to Stillwell Av
&lt;/a&gt;&lt;br/&gt;&lt;br/&gt;&lt;div id= 36886 class="plannedWorkDetail" &gt;&lt;/b&gt;Weekend, 12:01 AM Sat to 5 AM Mon, Apr 21 - 23
&lt;br&gt;
&lt;br&gt;Trains stop at 62 St-New Utrecht Av.
&lt;br&gt;
&lt;br&gt;For 45, 53 and 59 Sts, take the [R] instead. Transfer between trains at 36 St.
&lt;br&gt;
&lt;br&gt;&lt;/font&gt;For service &lt;i&gt;to&lt;/i&gt; 8 Av, Fort Hamilton Pkwy, 18, 20 Avs, Bay Pkwy, Kings Hwy, Avenue U and 86 St,
&lt;br&gt;take the [N] to 62 St-New Utrecht Av &lt;/font&gt;(&lt;a href=http://www.mta.info/nyct/service/NewUtrechtAv_access.htm target=blank&gt;&lt;font color=#0000FF&gt;&lt;u&gt;out-of-system transfer&lt;/u&gt;&lt;/font&gt;&lt;/font&gt;&lt;/a&gt;) or Stillwell Av and transfer to an Astoria-bound [N].
&lt;br&gt;
&lt;br&gt;For service &lt;i&gt;from&lt;/i&gt; these stations, take the [N] to New Utrecht Av-62 St &lt;/font&gt;(&lt;a href=http://www.mta.info/nyct/service/NewUtrechtAv_access.htm target=blank&gt;&lt;font color=#0000FF&gt;&lt;u&gt;out-of-system transfer&lt;/u&gt;&lt;/font&gt;&lt;/font&gt;&lt;/a&gt;) or
&lt;br&gt;36 St and transfer to a Coney Island-bound&amp;nbsp;[D]&amp;nbsp;or&amp;nbsp;[N].
&lt;br&gt;&lt;b&gt;
&lt;br&gt;&lt;/div&gt;&lt;/BODY&gt;&lt;/HTML&gt;&lt;/b&gt;&lt;br/&gt;
&lt;br/&gt;
&lt;br/&gt;
</text>
<Date>04/22/2012</Date>
<Time> 1:50PM</Time>
</line>

*view source*

*facepalm*

Lesson 3

Data. Not Style.

URI

Uniform Resource Identifier

Specify the format using a query paramter

/cats/ubuntu?format=json

Retrieve a resource's representation.

GET /cats/ubuntu

A GET must NEVER make changes to the resource or have side effects.

Create a new resource at a known URI

PUT /cats/ubuntu

The request body contains a representation of the resource to be created.

{name:ubuntu, color:brown, gender:male}

Modify an existing resource.

PUT /cats/ubuntu

The request body contains a representation of the attributes to modify

{gender:female}

Create a new resource in a collection when the URI is unknown

POST /cats

The request body contains a representation of the resource to be created.

{name:ubuntu, color:brown, gender:male}

Execute a controller

POST /cats/ubuntu/feed

POSTs are unpredictable and resending a POST request can have undesired side-effects.

Remove a resource from it's parent

DELETE /cats/ubuntu

D*:

After a DELETE, the resource should no longer be accessible at it's URI by future requests.

HTTP response status codes should be used to inform the client of the overall result.

200 OK

General-purpose success code, if none of the more specific ones apply.

201 Created

When a new resource has been successfully created.

202 Accepted

Only used by controllers. When a process is asynchronous but it was started successfully.

204 No Content

When the body is intentionally empty, such as for PUT, POST and DELETE requests.

301 Moved Permanently

If the API's architecture has changed and a resource now uses a new URI. The new URI should be specified in the response.

303 See Other

Refers the client to another URI, such as when a controller generates a resource.

307 Temporary Redirect

Tells the client that nothing was done with their request and they should resubmit to the specified URI.

400 Bad Request

General-purpose client-side error code, when no other 4XX code applies.

401 Unauthorized

If a resource requires authorization and there were incorrect or no credentials given.

403 Forbidden

If an authenticated user attempt to access a resource they are not allowed to.

404 Not Found

If the given URI can't be mapped to a resource.

405 Method Not Allowed

If an HTTP method is used on a URI that does not allow it, such as GET on a controller.

500 Internal Server Error

An generic error on the server. 500 means that it wasn't the client's fault and they should resubmit their request.

418 I'm A Teapot

If the client attempts to brew coffee and the HTCPCP Server is a teapot. The resulting body MAY be short and stout.

Sorry, but this is just the tip of the RESTful iceberg.

The good news: You're already way ahead of the curve.

Want to learn more?

http://lmgtfy.com/?q=REST