REST API를 설계하는 방법(How to Design a REST API)

REST를 조각으로 배우는 것은 한 가지이지만 이러한 모든 개념을 실제 애플리케이션 개발에 적용하는 것은 완전히 또 다른 과제입니다.

이 자습서에서는 네트워크 기반 응용 프로그램을위한 REST API를 설계하는 방법을 알려줍니다. 이 전체 연습에서 얻은 요점은 응용 프로그램 디자인 프로세스에서 REST 원칙을 적용하는 방법을 배우는 것입니다.

1. Identify the Resources – Object Modeling

REST API 기반 애플리케이션을 디자인하는 첫 번째 단계는 리소스로 표시될 오브젝트를 식별하는 것입니다.

네트워크 기반 응용 프로그램의 경우 개체 모델링이 훨씬 더 간단합니다. 장치, 관리되는 엔터티, 라우터, 모뎀 등과 같은 많은 항목이 있을 수 있습니다. 단순화를 위해 우리는 두 가지 리소스 만 고려할 것입니다.

• Devices
• Configurations

여기서 구성은 장치의 하위 자원일 수 있다. 장치에는 많은 구성 옵션이 있을 수 있습니다.

위 모델의 두 개체/리소스에는 integer id 속성인 고유 식별자가 있습니다.

2. Create Model URIs

이제 개체 모델이 준비되면 리소스 URI를 결정할 차례입니다. 이 단계에서는 리소스 URI를 디자인하는 동안 리소스와 하위 리소스 간의 관계에 중점을 둡니다. 이러한 리소스 URI는 API의 엔드포인트입니다.

이 응용 프로그램에서 장치는 최상위 리소스입니다. 그리고 구성은 장치 아래의 하위 리소스입니다. URI를 적어 보겠습니다.

/devices
/devices/{id}

/configurations
/configurations/{id}

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

이러한 URI는 동사나 연산을 사용하지 않습니다. URI에 동사를 포함하지 않는 것이 중요합니다. URI는 모두 명사여야 합니다.

3. Determine Resource Representations

이제 리소스 URI가 결정되었으므로 해당 표현에 대해 작업해 보겠습니다. 대부분의 표현은 XML 또는 JSON 형식으로 정의 됩니다. 데이터가 구성되는 방식을 보다 잘 표현하는 XML 예제를 살펴보겠습니다.

3.1. Collection Resource of Devices

컬렉션 리소스를 반환할 때는 해당 리소스에 대한 가장 중요한 정보만 포함합니다. 이렇게 하면 응답 페이로드의 크기가 작게 유지되므로 API의 성능이 향상됩니다.

<devices size="2">

	<link rel="self" href="/devices"/>

	<device id="12345">
		<link rel="self" href="/devices/12345"/>
		<deviceFamily>apple-es</deviceFamily>
		<OSVersion>10.3R2.11</OSVersion>
		<platform>SRX100B</platform>
		<serialNumber>32423457</serialNumber>
		<connectionStatus>up</connectionStatus>
		<ipAddr>192.168.21.9</ipAddr>
		<name>apple-srx_200</name>
		<status>active</status>
	</device>

	<device id="556677">
		<link rel="self" href="/devices/556677"/>
		<deviceFamily>apple-es</deviceFamily>
		<OSVersion>10.3R2.11</OSVersion>
		<platform>SRX100B</platform>
		<serialNumber>6453534</serialNumber>
		<connectionStatus>up</connectionStatus>
		<ipAddr>192.168.20.23</ipAddr>
		<name>apple-srx_200</name>
		<status>active</status>
	</device>

</devices>

3.2. Single Device Resource

컬렉션 URI와 반대로 단일 리소스 URI에는 특정 장치에 대한 완전한 정보가 포함됩니다. 또한 하위 리소스 및 기타 지원되는 작업에 대한 링크 목록도 포함되어 있습니다. 이렇게하면 REST API HATEAOS가 구동됩니다.

<device id="12345">
	<link rel="self" href="/devices/12345"/>

	<id>12345</id>
	<deviceFamily>apple-es</deviceFamily>
	<OSVersion>10.0R2.10</OSVersion>
	<platform>SRX100-LM</platform>
	<serialNumber>32423457</serialNumber>
	<name>apple-srx_100_lehar</name>
	<hostName>apple-srx_100_lehar</hostName>
	<ipAddr>192.168.21.9</ipAddr>
	<status>active</status>

	<configurations size="2">
		<link rel="self" href="/configurations" />

		<configuration id="42342">
			<link rel="self" href="/configurations/42342" />
		</configuration>

		<configuration id="675675">
			<link rel="self" href="/configurations/675675" />
		</configuration>
	</configurations>

	<method href="/devices/12345/exec-rpc" rel="rpc"/>
	<method href="/devices/12345/synch-config"rel="synch device configuration"/>
</device>

3.3. Collection Resource of Configurations

장치 컬렉션 표현과 유사하게, 최소한의 정보만으로 구성 컬렉션 표현을 작성하십시오.

<configurations size="20">
	<link rel="self" href="/configurations" />

	<configuration id="42342">
		<link rel="self" href="/configurations/42342" />
	</configuration>

	<configuration id="675675">
		<link rel="self" href="/configurations/675675" />
	</configuration>
	…
	…
</configurations>

장치 내부의 구성 컬렉션 표현은 최상위 구성 URI와 유사합니다.

유일한 차이점은 장치에 대한 구성이 두 개뿐이므로 두 개의 구성 항목만 장치 아래에 하위 리소스로 나열된다는 것입니다.

3.4. Single Configuration Resource

이제 단일 구성 자원 표현에는 관련 링크를 포함하여 이 자원에 대한 모든 가능한 정보가 있어야 합니다.

<configuration id="42342">
	<link rel="self" href="/configurations/42342" />
	<content><![CDATA[…]]></content>
	<status>active</status>
	<link rel="very big raw configuration script" href="/configurations/42342/raw" />
</configuration>

3.5. Collection Resource of Configuration under a Single Device

이 구성 하위 컬렉션은 기본 구성 컬렉션의 하위 집합이며 장치에만 해당됩니다.

기본 컬렉션의 하위 집합이므로 기본 컬렉션 과 다른 표현 데이터 필드를 작성하지 마십시오. 기본 컬렉션과 동일한 프레젠테이션 필드를 사용합니다.

<configurations size="2">
	<link rel="self" href="/devices/12345/configurations" />

	<configuration id="53324">
		<link rel="self" href="/devices/12345/configurations/53324" />
		<link rel="detail" href="/configurations/53324" />
	</configuration>

	<configuration id="333443">
		<link rel="self" href="/devices/12345/configurations/333443" />
		<link rel="detail" href="/configurations/333443" />
	</configuration>
</configurations>

이 하위 리소스 컬렉션에는 두 개의 링크가 있습니다. 하나는 하위 컬렉션 내부의 직접 표현 (예 : / devices/12345 / configurations / 333443이고 다른 하나는 기본 컬렉션의 위치 (예 : / configurations / 333443)를 가리 킵니다.

보다 고유한 방식으로 장치별 구성에 대한 액세스를 제공할 수 있고 보조 컬렉션에 표시되지 않는 일부 필드(디자인에 필요한 경우)를 마스킹할 수 있으므로 두 개의 링크가 있어야 합니다.

3.6. Single Configuration Resource under a Single Device

이 표현은 기본 컬렉션의 Configuration 표현과 정확히 유사한 표현을 가져야하거나 몇 개의 필드를 마스킹 할 수 있습니다.

이 하위 자원 표현에는 기본 표시에 대한 추가 링크도 있습니다.

<configuration id="11223344">
	<link rel="self" href="/devices/12345/configurations/11223344" />
	<link rel="detail" href="/configurations/11223344" />
	<content><![CDATA[…]]></content>
	<status>active</status>
	<link rel="raw configuration content" href="/configurations/11223344/raw" />
</configuration>

이제 다음 섹션으로 넘어가기 전에 놓치지 않도록 몇 가지 관찰 내용을 기록해 보겠습니다.

• 리소스 URI는 모두 명사입니다.
• URI는 일반적으로 리소스 모음과 단일 리소스의 두 가지 형식으로 제공됩니다.
• 수집은 1차 수집과 2차 수집의 두 가지 형태일 수 있다. 보조 컬렉션은 기본 컬렉션의 하위 컬렉션입니다.
• 각 리소스 / 컬렉션에는 적어도 하나의 링크, 즉 자체에 대한 링크가 포함되어 있습니다.
• 컬렉션에는 리소스에 대한 가장 중요한 정보만 포함됩니다.
• 리소스에 대한 전체 정보를 가져오려면 특정 리소스 URI에만 액세스하면 됩니다.
• 표현에는 추가 링크 (즉, 단일 장치의 메서드)가있을 수 있습니다. 여기서 메서드는 POST 메서드를 나타냅니다. 더 많은 속성을 갖거나 완전히 새로운 방식으로 링크를 형성 할 수도 있습니다.
• 우리는 아직 이러한 리소스에 대한 작업에 대해 이야기하지 않았습니다.

4. Assigning HTTP Methods

따라서 리소스 URI와 해당 표현이 이제 수정되었습니다. 응용 프로그램의 가능한 모든 작업을 결정하고 해당 작업을 리소스 URI에 매핑해 보겠습니다.

예를 들어, 네트워크 애플리케이션 사용자는 네트워크에서 장치를 찾아보기, 생성, 업데이트 또는 삭제하고 장치 구성을 생성/배포/제거할 수 있습니다. 따라서 이러한 작업을 각 리소스에 할당해 보겠습니다.

4.1. Browse all devices or configurations [Primary Collection]

HTTP GET /devices
HTTP GET /configurations

컬렉션 크기가 큰 경우 페이징 및 필터링을 적용할 수도 있습니다. 예를 들어 아래 요청은 컬렉션에서 처음 20개의 레코드를 가져옵니다.

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

4.2. Browse all configurations under a device [Secondary Collection]

HTTP GET /devices/{id}/configurations

대부분 작은 크기의 컬렉션이므로 여기서는 필터링 또는 정렬을 사용하도록 설정할 필요가 없습니다.

4.3. Browse a single device or configuration

장치 또는 구성의 전체 세부 정보를 가져오려면 단일 리소스 URI에 대해 GET 작업을 사용합니다.

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

4.4. Browse a single configuration under a device

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

하위 자원 표현은 기본 표시와 동일하거나 기본 표시의 하위 집합입니다.

4.5. Create a device or configuration

'CREATE'는 멱등원 연산이 아니며 'HTTP 프로토콜'에서 'POST'도 멱등수가 아닙니다. 따라서 'POST'를 사용하십시오.

HTTP POST /devices
HTTP POST /configurations

요청 페이로드에는 id 속성이 포함되지 않으므로 서버가 결정합니다. CREATE 요청에 대한 응답은 다음과 같습니다.

HTTP/1.1 201 Created
Content-Type: application/xml
Location: http://example.com/network-app/configurations/678678

<configuration id="678678">
	<link rel="self" href="/configurations/678678" />
	<content><![CDATA[…]]></content>
	<status>active</status>
	<link rel="raw configuration content" href="/configurations/678678/raw" />
</configuration>

4.6. Update a device or configuration

업데이트 작업은 멱등원 작업이며 HTTP PUT도 멱등수 메서드입니다. 따라서 업데이트 작업에 PUT 메서드를 사용할 수 있습니다.

HTTP PUT /devices/{id}
HTTP PUT /configurations/{id}

PUT 응답은 다음과 같이 보일 수 있습니다.

HTTP/1.1 200 OK
Content-Type: application/xml

<configuration id="678678">
	<link rel="self" href="/configurations/678678" />
	<content><![CDATA[. updated content here .]]></content>
	<status>active</status>
	<link rel="raw configuration content" href="/configurations/678678/raw" />
</configuration>

4.7. Remove a device or configuration

제거는 항상 DELETE 작업입니다.

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

성공적인 응답은 리소스가 삭제를 위해 큐에 대기된 경우(비동기 작업) 202(수락됨) 또는 리소스가 영구적으로 삭제된 경우(동기화 작업) 200(OK) / 204(콘텐츠 없음)여야 합니다(SHOULD).

비동기 작업의 경우 응용 프로그램은 성공/실패 상태를 추적할 수 있는 작업 ID를 반환해야 합니다.

하위 리소스가 시스템에서 삭제될 때의 동작을 결정할 때 충분한 분석을 해야 합니다. 일반적으로 이러한 요청에서 리소스를 일시 삭제하여 INACTIVE 상태로 설정할 수 있습니다.

이 방법을 따르면 다른 위치에서도 해당 참조를 찾아 제거할 필요가 없습니다.

4.8. Applying or Removing a configuration on/from a device

실제 응용 프로그램에서는 장치에 구성을 적용하거나 기본 컬렉션이 아닌 장치에서 구성을 제거할 수 있습니다. 이 경우 PUT 및 DELETE 메서드는 멱등수 특성 때문에 사용해야 합니다.

//Apply Configuration on a device
HTTP PUT /devices/{id}/configurations

//Remove Configuration on a device
HTTP DELETE /devices/{id}/configurations/{configId}

5. More Actions

지금까지는 개체 모델과 URI만 디자인한 다음 HTTP 메서드 또는 이에 대한 작업을 결정했습니다. 응용 프로그램의 다른 측면에서도 작업해야합니다.

1) Logging
2) Security
3) Discovery etc.

이 예제 응용 프로그램의 소스 코드를 참조하여 더 잘 이해할 수 있습니다.