-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathrest-overview.html.md.erb
93 lines (82 loc) · 4.09 KB
/
rest-overview.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
---
title: REST Overview
owner: API
---
<strong><%= modified_date %></strong>
## <a id='what-is-rest'></a> What is REST?
REST stands for **RE**presentational **S**tate **T**ransfer, which describes the architectural style of using HTTP to make remote procedure calls. Instead of using a heavy RPC mechanisms such as XML-RPC or SOAP, a REST web API uses the design of the HTTP protocol to define the remote methods.
Almost everyone with a technical background understands what an HTTP GET call is, but it is less understood that HTTP has a vocabulary of operations that is very similar to the CRUD calls needed to maintain the state of entities. What most people call an URL is often called a resource in REST. Each resource can be called with a given operation which is called a HTTP method. Here is a list of the most common HTTP methods called in REST and the CRUD equivalent:
| REST | CRUD |
| ------ | ------ |
| POST | Create |
| GET | Read |
| PUT | Update |
| DELETE | Delete |
## <a id='example'></a> REST Example: User API
Let's go through an example of a fictional REST API for managing users. The following table shows the different resources and methods to manipulate user entities:
<table>
<thead>
<tr>
<th>REST Call</th>
<th>HTTP Method</th>
<th>Resource (URL)</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>List users</td>
<td>GET</td>
<td>http://swisscom.ch/api/user</td>
<td>
Get a list of the users in the system, which in most cases will be a summary view. It is also common to allow the use of keywords via attributes such as http://swisscom.ch/api/user?firstName=Humpty to limit the list to users have the first name of "Humpty".
</td>
</tr>
<tr>
<td>Create user</td>
<td>POST</td>
<td>http://swisscom.ch/api/user</td>
<td>
This call makes a POST call to the same URL resource as the list users. You will need to send the create attributes in the post request. This is commonly done by sending a payload of attributes in JSON format. For example, to create a user in our system named Humpty Dumpty, we would send a payload like this:
<pre>{
"firstName" : "Humpty",
"lastName" : "Dumpty",
"userName" : "hdumpty",
"email" : "[email protected]",
"status" : "active",
}</pre>
</td>
</tr>
<tr>
<td>Get user</td>
<td>GET</td>
<td>http://swisscom.ch/api/user/hdumpty</td>
<td>Get a user and all details. Note the URL has the unique ID representing the user.</td>
</tr>
<tr>
<td>Update user</td>
<td>PUT</td>
<td>http://swisscom.ch/api/user/hdumpty</td>
<td>
Update the user w/attributes sent in the payload, just like the create user request. For example, to change the status of Humpty Dumpty to "broken":
<pre>{
"firstName" : "Humpty",
"lastName" : "Dumpty",
"userName" : "hdumpty",
"email" : "[email protected]",
"status" : "broken",
}</pre>
</td>
</tr>
<tr>
<td>Delete user</td>
<td>DELETE</td>
<td>http://swisscom.ch/api/user/hdumpty</td>
<td>Since no one could put Humpty back together again, the DELETE call to the hdumpty resource URL will remove him.</td>
</tr>
</tbody>
</table>
## <a id='why-rest'></a> Why REST?
Swisscom has decided to expose services via REST due to the simple nature of REST APIs for the following reasons:
* **Easy to understand**: Instead of using a more complex RPC mechanism such as SOAP, a REST API helps developers get up and running quickly. REST is easy to read and understand, and can be tested by using a standard browser.
* **Language neutral**: REST is easy to implement in any language - every modern programming language will have HTTP and JSON encoding methods built into the language. Most languages also have multiple open source libraries that make REST calls even easier.