Restful Api에 대해서 정리 글
리소스가 무엇인가?
- 기본 데이터의 표현. 이름을 지정할 수 있는 정보들..?
ex) 스타크래프트의 미네랄, 가스
1.1 싱글톤, 콜렉션 리소스
고객들(customers)은 Collection, 고객(customer)은 Singleton.
이를 url 상으로는
/customers
/customers/{customerId}
1.2 하위 리소스들
하기와 같이 하위 리소스들의 표현
/customers/{customerId}/accounts
/customers/{23}/accounts/{accountid}
1.3 URI를 잘 설계해야하는 이유
REST API의 리소스 모델을 API의 잠재적 클라이언트에 전달하는 URI를 만들어야 합니다. 리소스 이름이 잘 지정되면 API가 직관적이고 사용하기 쉽습니다. 제대로 수행되지 않으면 동일한 API를 사용하고 이해하기 어려울 수 있습니다
2. 모범 사례
2.1. 자원을 나타내기 위해 명사 사용
RESTful URI는 동작(동사)을 참조하는 대신 사물(명사)인 리소스를 참조해야 합니다. 명사에는 동사가 갖지 않는 속성이 있기 때문입니다. 리소스의 몇 가지 예는 다음과 같습니다.
시스템 사용자
사용자 계정
네트워크 장치 등
리소스 URI는 다음과 같이 설계할 수 있습니다.
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}
더 명확하게 하기 위해 리소스 원형 을 네 가지 범주(문서, 컬렉션, 저장소 및 컨트롤러)로 나누겠습니다. 그러면 항상 리소스를 하나의 원형에 넣은 다음 명명 규칙을 일관되게 사용하는 것이 가장 좋습니다 .
균일성을 위해 둘 이상의 원형이 혼합된 리소스를 설계하려는 유혹에 저항하십시오.
2.1.1. 문서
문서 리소스는 개체 인스턴스 또는 데이터베이스 레코드와 유사한 단일 개념입니다.
REST에서는 리소스 컬렉션 내의 단일 리소스로 볼 수 있습니다. 문서의 상태 표현에는 일반적으로 값이 있는 필드와 다른 관련 리소스에 대한 링크가 모두 포함됩니다.
"단수" 이름을 사용하여 문서 리소스 원형을 나타냅니다.
? http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin
2.1.2. 수집
컬렉션 리소스는 서버에서 관리하는 리소스 디렉터리입니다.
클라이언트는 컬렉션에 추가할 새 리소스를 제안할 수 있습니다. 그러나 새 리소스를 생성할지 여부를 선택하는 것은 컬렉션 리소스에 달려 있습니다.
컬렉션 리소스는 포함할 항목을 선택하고 포함된 각 리소스의 URI도 결정합니다.
"복수" 이름을 사용하여 컬렉션 리소스 원형을 나타냅니다.
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
2.1.3. 가게
저장소는 클라이언트 관리 리소스 저장소입니다. 저장소 리소스를 사용하면 API 클라이언트가 리소스를 넣고 다시 가져오고 삭제할 시기를 결정할 수 있습니다.
저장소는 새 URI를 생성하지 않습니다. 대신 저장된 각 리소스에는 URI가 있습니다. 리소스가 저장소에 처음 넣을 때 클라이언트가 URI를 선택했습니다.
상점 리소스 원형을 나타내기 위해 "복수형" 이름을 사용하십시오.
2.1.4. 제어 장치
컨트롤러 리소스는 절차적 개념을 모델링합니다. 컨트롤러 리소스는 매개 변수와 반환 값, 입력 및 출력이 있는 실행 가능한 함수와 같습니다.
"동사"를 사용하여 컨트롤러 원형을 나타냅니다.
http://api.example.com/cart-management/users/{id}/cart/checkout http://api.example.com/song-management/users/{id}/playlist/play
2.2. 일관성이 핵심입니다
모호성을 최소화하고 가독성과 유지 관리성을 극대화하기 위해 일관된 리소스 명명 규칙과 URI 형식을 사용합니다. 일관성을 유지하기 위해 아래 디자인 힌트를 구현할 수 있습니다.
2.2.1. 슬래시(/)를 사용하여 계층적 관계를 나타냅니다.
슬래시(/) 문자는 리소스 간의 계층적 관계를 나타내기 위해 URI의 경로 부분에 사용됩니다. 예를 들어
http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
2.2.2. URI에 후행 슬래시(/)를 사용하지 마십시오.
URI 경로 내의 마지막 문자인 슬래시(/)는 의미론적 값을 추가하지 않으며 혼동을 줄 수 있습니다. URI에서 삭제하는 것이 좋습니다.
http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices /This is much better version/
2.2.3. 하이픈(-)을 사용하여 URI의 가독성 향상
사람들이 쉽게 스캔하고 해석할 수 있도록 URI를 만들려면 하이픈(-) 문자를 사용하여 긴 경로 세그먼트에서 이름의 가독성을 높이십시오.
http://api.example.com/devicemanagement/manageddevices/
http://api.example.com/device-management/managed-devices /This is much better version/
2.2.4. 밑줄( _ )을 사용하지 마십시오.
하이픈 대신 밑줄을 사용하여 구분 기호로 사용할 수 있습니다. 그러나 응용 프로그램의 글꼴에 따라 일부 브라우저나 화면에서 밑줄(_) 문자가 부분적으로 가려지거나 완전히 숨겨질 수 있습니다.
이러한 혼동을 피하려면 밑줄(_) 대신 하이픈(-)을 사용하십시오.
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable
2.2.5. URI에 소문자 사용
편리할 경우 소문자가 URI 경로에서 일관되게 선호되어야 합니다.
http://api.example.org/my-folder/my-doc //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
http://api.example.org/My-Folder/my-doc //3
위의 예에서 1과 2는 같지만 3은 My-Folder 를 대문자로 사용하므로 그렇지 않습니다.
2.3. 파일 확장자를 사용하지 마십시오
파일 확장자는 보기에 좋지 않으며 어떤 이점도 추가하지 않습니다. 이를 제거하면 URI 길이도 줄어듭니다. 보관할 이유가 없습니다.
위의 이유와는 별도로 파일 확장자를 사용하여 API의 미디어 유형을 강조 표시하려면 헤더를 통해 전달되는 미디어 유형에 의존 하여 본문의 콘텐츠를 처리하는 방법을 결정해야 합니다.Content-Type
http://api.example.com/device-management/managed-devices.xml /Do not use it/
http://api.example.com/device-management/managed-devices /This is correct URI/
2.4. URI에 CRUD 함수 이름을 사용하지 마십시오.
CRUD 기능을 나타내기 위해 URI를 사용해서는 안 됩니다. URI는 리소스를 고유하게 식별하는 데만 사용되어야 하며 리소스에 대한 작업이 아닙니다.
어떤 CRUD 기능이 수행되는지 나타내기 위해 HTTP 요청 방법을 사용해야 합니다.
HTTP GET http://api.example.com/device-management/managed-devices //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices //Create new Device
HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id
2.5. 쿼리 구성 요소를 사용하여 URI 수집 필터링
특정 리소스 속성에 따라 정렬, 필터링 또는 제한되는 리소스 모음이 필요한 요구 사항이 있는 경우가 많습니다.
이 요구 사항의 경우 새 API를 생성하지 마십시오. 대신 리소스 컬렉션 API에서 정렬, 필터링 및 페이지 매김 기능을 활성화하고 입력 매개 변수를 쿼리 매개 변수로 전달하십시오.
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
