StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
text
Body
copied!<p>You can use a framework to do a lot of the work for you, but what happens under the hood is no magic. In some way, the URIs map to some database tables. They don't refer to a certain directory structure, but try to explain a hierarchical relationship between the resources.</p> <p>For example, let's say that we're modelling a university. The elements in the database are stored in one of two tables, either <em>Faculties</em> or <em>Courses</em>. The Faculties table consists of rows describing the Faculty of Law, Faculty of Medicine and so on. It has a unique <em>faculty_id</em> column and then columns to describe whatever we need. The Courses table has a unique <em>course_id</em> column and a foreign key <em>faculty_id</em> column, to tell which faculty the course belongs to.</p> <p>A RESTful way of designing this API might be</p> <ul> <li><code>/faculties</code> to get a list of all faculties, retrieved with <code>SELECT * FROM Faculties</code></li> <li><code>/faculties/2</code> to get the information about a certain faculty, retrieved with <code>SELECT * FROM Faculties WHERE faculty_id=2</code></li> <li><code>/faculties/2/courses</code> to get all the courses belonging to a certain faculty, retrieved with <code>SELECT * FROM Courses WHERE faculty_id=2</code></li> <li><code>/faculties/2/courses/15</code> to retrieve a certain course, if it indeed belongs to faculty 2, retrieved with <code>SELECT * FROM Courses WHERE faculty_id=2 AND course_id=15</code></li> </ul> <p>The exact implementation of this depends on the programming language (and possibly framework) that you choose, but at some point you need to make choices about how you should be able to query the database. This is not obvious. You need to plan it carefully for it to make sense!</p> <p>The result from the database will of course have to be encoded in some way, typically XML or JSON (but other representations are just as fine, although maybe not as common).</p> <p>Apart from this, you should also make sure to implement the four verbs correctly so that they match the SQL commands (<code>GET</code>=<code>SELECT</code>, <code>POST</code>=<code>INSERT</code>, <code>PUT</code>=<code>UPDATE</code>, <code>DELETE</code>=<code>DELETE</code>), handle encoding negotiation correctly, return proper HTTP response codes and all the other things that are expected of a RESTful API.</p> <p>As a final piece of advice: If you do this neatly, it'll become <em>so much easier</em> for you to design your mobile apps. I really can't stress this enough. For example, if you on a <code>POST</code> request return the full entry as it now looks in the database, you can immediately store it on the phone with the correct ID, and you can use the same code for rendering the content as you would if it had been downloaded using a <code>GET</code> request. Also, you won't trick the user by updating prematurely, before you know whether that request was successful (mobile phones lose connection a lot).</p> <p><strong>EDIT:</strong> To answer your question in the comments: Creating an API can be seen as a form of art, and should probably not involve any coding in the design stage. The API should be meaningful and not rely on a particular implementation (i.e. a different database choice shouldn't affect your API). Your next task will be to create ties between the human-readable structure of the API and your database (regardless of whether it's relational or something else). So yes, you will need to do some translation, but I don't see how the query string would help you. The typical structure is <code>api.my.website/collection/element/collection/element</code>. Queries can be used for filtering. You could for example write <code>example.com/resource?since=2012-06-01</code> to retrieve a subset of the elements from your 'resource' collection, but the meaning of this particular query is to retrieve something you <em>couldn't</em> express with an unique ID.</p> <p>The way I understand it, you think that incoming requests must always go to separate files based on the way PHP and HTTP servers work. This is <strong>not</strong> the case. You can <a href="http://www.kavoir.com/2010/02/use-php-to-handle-all-incoming-url-requests-in-a-seo-friendly-manner.html" rel="nofollow">configure your web server to route every request to a single PHP file</a> and then parse <code>$_SERVER['REQUEST_URI']</code>. Depending on your choice of HTTP server your mileage might vary, but this is essentially what you want to do.</p> <p>By googling I found <a href="http://blog.programmableweb.com/2011/09/23/short-list-of-restful-api-frameworks-for-php/" rel="nofollow">a list of frameworks for PHP</a> but I don't know any of them. There are others, though, and I also recently heard someone mention <a href="http://www.apifydoc.com/" rel="nofollow">Apify</a>, although I can't tell you much about that either. PHP is probably one more the more common choices for implementing an API. <a href="http://php.net/manual/en/book.curl.php" rel="nofollow">cURL</a>, however, is a library/tool that's only designed to connect to <em>other</em> websites, as far as I know. You can certainly use <a href="http://curl.haxx.se/" rel="nofollow">the command line version of it</a> to debug your API, but I don't think you'll have much use for it on the server side.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

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