How to design a REST API

Learning REST in stages is one thing, but applying all the learned concepts to actual application design is another challenge entirely. In this tutorial, we will learn to design a REST API for web-based applications . Please note that the main content of the whole exercise is to learn how to apply REST principles in the design process .

Steps to design a REST service

Recognition object model

Create model URI

Determine the representation

Assign HTTP method

More actions

Recognition object model

Based on REST API first step of the application is to - determine a resource objects presented.

For web-based applications, object modeling is much simpler. There can be many things, such as devices, management entities, routers, modems, etc. For simplicity, we will only consider two resources, namely

equipment
structure

The configuration here is a sub-resource of the device. The device can have many configuration options.

Please note that both objects / resources in our model above will have a unique identifier, which is the integer id attribute.

Create model URI

Now, when the object model is ready, it's time to determine the resource URI . In this step, the design resource URI time - focuses on the relationship between resources and sub-resources. These resource URIs are the endpoints of RESTful services .

In our application, the device is the top resource. And configuration is a sub-resource under the device. Let's write down the URI .

/devices

/devices/{id}

/configurations

/configurations/{id}

/devices/{id}/configurations

/devices/{id}/configurations/{id}

Please note that these URIs do not use any verbs or operations . It is very important not to include any verbs in the URI . URIs can only be nouns.

Determine the representation

Now that the resource URIs are determined , let us begin to study their representation. Usually, the representation is defined in XML or JSON format. We think of XML examples as more expressive examples of how to compose data.

Equipment resource collection

When returning to collecting resources, only the most important information about the resource is included. This will keep the size of the payload small and therefore will improve the performance of the REST API .

<deviceFamily>apple-es</deviceFamily>

<name>apple-srx_200</name>

<status>active</status>

</device>

<deviceFamily>apple-es</deviceFamily>

<name>apple-srx_200</name>

<status>active</status>

</device>

</devices>

单设备资源

与集合URI相反，此处在此URI中包含设备的完整信息。在这里，还包括子资源和其他支持的操作的链接列表。这将使您的REST API HATEOAS驱动。

<deviceFamily>apple-es</deviceFamily>

<name>apple-srx_100_lehar</name>

<hostName>apple-srx_100_lehar</hostName>

<status>active</status>

</configuration>

</configuration>

</configurations>

</device>

配置资源收集

与设备集合表示类似，仅使用最少的信息即可创建配置集合表示。

</configuration>

</configuration>

...

</configurations>

请注意，configurations内部的集合表示device形式类似于顶级configurationsURI。唯一的区别是，configurations一个设备只有两个，因此只有两个配置项被列为设备下的子资源。

单一配置资源

现在，单个配置资源表示必须具有有关该资源的所有可能信息，包括相关链接。

<status>active</status>

</configuration>

单个设备下的配置资源收集

配置的此资源集合将是配置的主要集合的子集，并且仅特定于设备。由于它是主要集合的子集，因此请勿创建与主要集合不同的表示形式数据字段。使用与主要集合相同的表示字段。

</configuration>

</configuration>

</configurations>

请注意，此子资源集合具有两个链接。一个子集，即内部的直接表现/devices/12345/configurations/333443和其他指向它的位置主要采集即/configurations/333443。

具有两个链接是必不可少的，因为您可以以更独特的方式提供对特定于设备的配置的访问，并且您将能够屏蔽某些字段（如果设计需要），这些字段在辅助集合中将不可见。

单个设备下的单个配置资源

该表示形式应具有与主要集合中的Configuration表示形式完全相同的表示形式，或者您可以屏蔽很少的字段。

此子资源表示形式还将具有指向其主要表示形式的附加链接。

<status>active</status>

</configuration>

现在，在继续进行下一部分之前，让我们记下一些观察结果，以免您错过它们。

资源URI都是名词。
URI通常采用两种形式-资源收集和单一资源。
收集可以采用两种形式：一次收集和二次收集。次要集合是仅主要集合中的子集合。
每个资源/集合至少包含一个链接，即指向自身的链接。
集合仅包含有关资源的最重要信息。
要获取有关资源的完整信息，您仅需要通过其特定的资源URI进行访问。
表示形式可以具有额外的链接（即单个设备中的方法）。这里method代表一个POST方法。您也可以以全新的方式拥有更多属性或形成链接。
我们还没有谈论这些资源上的操作。

分配HTTP方法

因此，我们的资源URI及其表示形式现已修复。让我们确定应用程序中可能的操作，并将这些操作映射到资源URI。我们的网络应用程序的用户可以执行浏览，创建，更新或删除操作。因此，让我们分配它们。

浏览所有设备或配置[主集合]

HTTP GET /devices

HTTP GET /configurations

如果集合很大，则也可以应用分页和过滤。例如，以下请求将从集合中获取前20条记录。

HTTP GET /devices?startIndex=0&size=20

HTTP GET /configurations?startIndex=0&size=20

浏览所有设备或配置[次级集合]

HTTP GET /devices/{id}/configurations

这主要是一个小规模的集合-因此无需在此处启用过滤或筛选。

浏览单个设备或配置[主集合]

要获取设备或配置的完整详细信息，请GET对单个资源URI使用操作。

HTTP GET /devices/{id}

HTTP GET /configurations/{id}

浏览单个设备或配置[次级集合]

HTTP GET /devices/{id}/configurations/{id}

子资源表示将与主要表示相同或作为其子集。

创建设备或配置

创建不是幂等操作，并且在HTTP协议中-POST也不是幂等。因此，请使用POST。

HTTP POST /devices

HTTP POST /configurations

请注意，请求有效负载将不包含任何id属性，因为服务器负责决定它。创建请求的响应如下所示：

HTTP/1.1 201 Created

Content-Type: application/xml

Location: http://example.com/network-app/configurations/678678

<status>active</status>

</configuration>

更新设备或配置

更新操作是幂等操作，HTTPPUT也是幂等方法。因此我们可以使用PUT方法进行更新操作。

HTTP PUT /devices/{id}

HTTP PUT /configurations/{id}

PUT响应可能如下所示。

HTTP/1.1 200 OK

Content-Type: application/xml

<status>active</status>

</configuration>

删除设备或配置

删除始终是一项DELETE操作。

HTTP DELETE /devices/{id}

HTTP DELETE /configurations/{id}

成功的响应应该是202 (Accepted)资源是否已排队删除（异步操作），或者200 (OK) /204 (No Content)如果资源已永久删除（同步操作）。

在异步操作的情况下，应用程序应返回可以跟踪成功/失败状态的任务ID。

请注意，当从系统中删除子资源时，您应该进行足够的分析以确定行为。通常，您可能希望在这些请求中“软件删除”资源-换句话说，将其状态设置为“不活动”。通过遵循这种方法，您也无需在其他地方查找和删除其引用。

从设备应用或删除配置

在实际的应用程序中，您将需要在设备上应用配置–或者您可能希望从设备（而不是从主集合中）删除配置。在这种情况下，由于其幂等性质，应使用PUT和DELETE方法。

//Apply Configuration on a device

HTTP PUT /devices/{id}/configurations

//Remove Configuration on a device

HTTP DELETE /devices/{id}/configurations/{id}

更多操作

到目前为止，我们仅设计了对象模型，URI，然后确定了HTTP方法或对其的操作。您还需要处理应用程序的其他方面：

1）记录
2）安全
3）发现等

在下一篇文章中，我们将使用Java创建此应用程序以更详细地了解。

How to design a REST API

Guess you like