*RESTful API RESTful API의 URI와 HTTP 설계 원칙

*index 1. RESTful API 소개 2. Identifier Design with URIs 3. Interaction Design with HTTP 4. Metadata Design (Next Seminar) 5. Representation Design (Next Seminar)

1. RESTful API 소개

용어 정의 URI (The Uniform Resource Identifier) - 인터넷에 있는 자원을 나타내는 유일한 주소 HTTP (The HyperText Transfer Protocol) - HTML 문서와 같은 자원들을 가져올 수 있도록 해주는 프로토콜 HTML (HyperText Mark-up Language) - 웹 페이지를 만들기 위한 언어 REST (Representational State Transfer) - 월드 와이드 웹(www) 과 같은 소프트웨어 아키텍처의 한 형식 - 자원을 정의하고, 자원에 대한 주소를 지정하는 방법 전반을 뜻한다. API (Application Programming Interfaces) - 응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페 이스 - 예를 들어, 파일 제어, 창 제어, 문자 제어 등

* RFC(Request For Comments) : 인터넷국제표준화기구(IETF: Internet Engineering Task Force)에서 인터넷에서 기술을 구현하는 필요한 상세한 절차, 기본 틀 등을 제공하는 공문서 간행물 배경 웹 표준 정의 - Fielding과 Tim Berners-Lee 외 여러 사람들은 웹의 성장을 위해 일을 함 - 그 결과 HTTP의 새로운 버전인 HTTP/1.1과 URI의 문법을 공식화 함 (RFC 3986) REST - 2000년에 Fielding이 위 웹 표준을 따르는 “자원을 정의하고, 자원에 대한 주소를 지정하는 방법 전반”에 대한 웹 구조적인 스타일을 정의한 것 정리하자면.. REST는 HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하여, 여러 형태의 Representation(JSON, XML, TEXT 등)으로 응답한다. 다양한 클라이언트의 등장 - 웹의 발전과 함께 다양한 브라우저가 생겨났고, Android, ios 같은 모바일 외 다양한 플랫폼 등장 - 당연히 Server는 이러한 멀티 플랫폼과 통신할 수 있어야 했다. - 자원에 대해 구조를 정의하고 이용하는 방법에 대해 REST에 대한 관심 증가

RESTful API란? client Web API Web Service Backend Request Response RESTful API는 API다. ( O ) API는 RESTful API다. ( X ) - 응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페 이스 - 예를 들어, 파일 제어, 창 제어, 문자 제어 등 API (Application Programming Interfaces) Web API 앞서 REST에 관심을 가졌던 배경 - Web에서 Client와 Server는 “Web API”를 통해 통신한다. RESTful API는 API의 한 종류이다. - 멀티 플랫폼과의 통신을 위해 자원을 정의하고 관리하는 방법이 필요 - REST에 관심 증가 REST(ful) API는 REST 기반으로 서비스 API를 구현한 것이다.

2. Identifier Design with URIs

URI란? URL vs URI - URL (Uniform Resource Locator) - 자원의 위치 - 웹 상에 서비스를 제공하는 각 서버들에 있는 파일의 위치를 표시하기 위한 것 - URI (Uniform Resource Identifier) - 통합 자원 식별자 - 인터넷에 있는 자원을 나타내는 유일한 주소 - 자원에 접근하기 위해 사용되는 절차 - 어떤 자원을 가지고 있는 특정한 컴퓨터 - 컴퓨터 상의 유니크한 자원의 이름(파일명) - URI 하위개념에 URL 포함 * 최근에 URL보다 URI라는 용어를 쓰는 이유은 서버 내 디렉터리 구조를 노출시키는 URL의 보안적 이슈와 관련하여, URI에 해당하는 Controller 즉 함수를 실행함으로써 결과를 받는다. URI URL http://test.com/company/location http://service.com/tv/turn/on http://test.com/work/sample.pdf

URI Format URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ] - URI를 어떤 규칙에 따라 기술하고 자원(데이터)에 어떻게 접근하는지 지정 - http, ftp … - 서버명과 도메인명으로 구성 - 서버명 – www, api, develop … - 도메인명 – test.co.kr - 폴더명과 파일명으로 구성 - 서버 내부 자원의 위치를 나타낸다.

URI Format의 설계 원칙 http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares Rule : 앞에 붙는 슬래쉬(/)는 계층 관계를 나타내기 위해 사용되어야 한다. Rule : 뒤에 붙는 슬래쉬(/)는 URI에 포함되면 안된다. http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post 애플리케이션의 폰트에 따라서 언더바는 문자가 깨져 보이거나 숨겨져 보이기도 한다. 따라서 이런 혼동을 피하기 위해서 언더바 대신에 하이픈(-)을 사용하기를 권장 1. http://api.canvas.restapi.org/shapes/ 2. http://api.canvas.restapi.org/shapes 대부분의 웹에서는 위 두 개의 URIs를 동일하게 간주한다. 하지만 URI는 모든 문자는 식별자로 쓰인다. 그렇기 때문에 위 두 개의 URIs는 각각 다른 리소스에 접근한 것으로 간주한다. 따라서 REST API는 명확해야 한다. (하지만 경우에 따라서 뒤에 슬래쉬가 붙은 경우에도 301 응답코드를 리턴하면서 redirect를 제공하기도 한다.) Rule: 하이픈(-)은 URI의 가독성을 향상시키기 위해 사용되어야 한다. Rule: 언더바(_)는 URI에서 사용되면 안 된다.

URI Format의 설계 원칙 대문자는 때때로 문제를 야기할 수 있기 때문에 편리하게 소문자를 선호한다. 1. http://api.example.restapi.org/my-folder/my-doc 2. HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc 3. http://api.example.restapi.org/My-Folder/my-doc •1번은 괜찮음 •2번은 1번과 같은 것으로 간주 (RFC 3986) •3번은 1,2번과 같지 않다!! Rule: URI path에서 소문자 사용을 권장한다. - 웹에서 URIs의 (.)은 파일 이름과 확장자를 분리하기 위해서 사용된다. - REST API는 메세지의 엔티티 바디의 형식을 나타내기 위해 URIs에 커스터마이징한 파일 확장자를 포함하면 안된다. - 대신에 body의 내용을 처리하기 위해, Content-Type 헤더를 통해 커뮤니케이션되는 media type을 이용해야 한다. •http://api.college.restapi.org/students/3249234/transcripts/2005/fall.json •파일 확장자가 붙으면 안된다. •http://api.college.restapi.org/students/3249234/transcripts/2005/fall •Request Header의 Accept라는 항목을 통해 client는 제공받는 형식을 지정할 수 있다. Rule: URI에서 파일확장자는 포함되어서는 안된다.

URI Authority의 설계 원칙 API의 최상위 레벨의 도메인 그리고 첫 번째 서브도메인의 이름은 서비스가 무엇인지 구분할 수 있는 것이어야 한다. 예를 들어 API의 풀 도메인은 서브도메인으로 "api"를 붙여야 한다. http://api.soccer.restapi.org Rule: API에는 일관된 서브 도메인 이름이 사용되어야 한다. Rule: 마찬가지로 개발자 포탈에도 일관된 서브 도메인 이름이 사용되어야 한다. 대부분의 REST API는 관련 웹사이트를 가지고 있다. 개발자 포털 -> 문서, 포럼, API access key를 제공 등등 마찬가지로 "developer"라는 서브 도메인을 붙여주어야 한다. http://developer.soccer/restapi.org

Resource Modeling URI Resource Modeling - URI path와 REST API의 리소스 모델링하는 것은 비슷I - leagues -> seattle -> teams -> trebuchet - 이런식으로 REST API의 경우에도 리소스를 계층적으로 구성한다는 것이 유사 http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Resource Archetypes URI Resource Archetypes REST API는 4개의 리소스 타입을 가진다. 1. Document - 객체 인스턴스 또는 데이터베이스의 레코드와 유사한 단일 개념 - Document의 state는 어떤 값을 나타내는 Filed와 다른 Document로 연결되는 Link가 있다. 2. Collection - 서버 관리 자원(Resource)의 디렉토리 개념 - Resource들을 모아두는 곳이라고 생각하면 된다. 3. Store - Collection과 비슷하게 Resource들을 모아두는 디렉토리이다. - Collection과 다른 점은 Client에 의해 관리되어진다. 4. Controller - 실행 가능한 함수같은 개념 - REST API 주로 이 Controller에 의존하는데, 하나의 Controller가 CRUD 중 하나에 매핑되어 작업을 수행한다. (Collection-c) / (store-s) / (document-d) c/ s/ d Contains s Stores d

URI Path의 설계 원칙 http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio Rule: Document 이름으로 단수형 명사가 사용되어야 한다. Rule: collection 이름으로 복수형 명사가 사용되어야 한다. Rule: Store 이름으로 복수형 명사가 사용되어야 한다. Rule: Controller 이름으로 동사 또는 동사 구문이 사용되어야 한다. Rule: 변수형의 path는 ID 기반의 값으로 대체되어야 한다. Rule: CRUD 함수 이름은 URI에서 사용되면 안된다. *dedupe : 데이터 중복제거, UUID : 식별자를 중앙관리 시스템에서 부여해주면 간단하지만, 독립적으로 개발되고 있는 시스템에 하는 것은 쉽지 않기 때문에 범용적으로 쓰이는 고유 식별자이다. http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players http://api.music.restapi.org/artists/mikemassedotcom/playlists http://api.college.restapi.org/students/morgan/register http://api.example.restapi.org/lists/4324/dedupe http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/21 → Player ID http://api.soccer.restapi.org/games/3fd65a60-cb8b-11e0-9572-0800200c9a66 → Game ID를 UUID형식으로 나타낸 것 - 여기서 CRUD 함수는 HTTP Method(GET, POST, PUT, DELETE 등)을 의미 - DELETE /users/1234 (O) - GET /deleteUser?id=1234 (X) - GET /deleteUser/1234 (X) - DELETE /deleteUser/1234 (X) - POST /users/1234/delete (X)

URI Query의 설계 원칙 - 1) GET /users - 2) GET /users?role=admin - 1)의 경우는 모든 user의 정보를 받을 것이다. - 2)의 경우에는 user 중 admin 역할을 가진 user의 정보를 받는다 (filtering) Rule: URI의 Query 부분은 Collection이나 Store를 필터링 하기 위해 사용되어야 한다. Rule: URI의 Query 부분은 Collection이나 Store의 결과를 페이징 하기 위해 사용되어야 한다. - 페이징 한다는 것? 여러 개의 결과 리스트를 페이지 단위로 나눈다는 의미 - Ex) GET /users?pageSize=25&pageStartIndex=50 - pageSize : Response에 리턴 될 데이터(element)의 양을 지정 - pageStartIndex : Index의 0으로 시작될 부분을 지정 - 위 예제는 user 데이터 중 50번 째부터 25개의 데이터를 받겠다는 의미

3. Interaction Design with HTTP

* curl: command line 용 data transfer tool Request Method Rule: GET을 이용하여 자원을 얻는다. - Jsonplaceholder라는 REST API 요청 테스트 사이트로 cURL 날린 결과 (curl은 기본적으로 GET 요청을 한다.) - Resonpse body - HTTP Status Code - Reqeust Line (Get 요청이 사용되었음을 나타냄)

Request Method Rule: GET과 POST를 사용하여 다른 요청 방법을 터널링 해서는 안된다. - 터널링? 다른 용도로 오,남용 한다는 의미 - 즉, GET과 POST는 Resource를 얻거나 생성하는 용도로만 사용해야 한다. Rule: HEAD를 이용하여 Response의 Header 정보를 얻는다. - CURL의 “head” 옵션을 이용하여 header 정보를 얻을 수 있다.

Request Method Rule: DELETE를 이용하여 자원을 제거한다. Rule: OPTIONS를 이용하여 자원의 이용 가능한 Method의 메타데이터 정보를 얻는다. Rule: PUT을 이용하여 자원을 저장하거나 업데이트한다. Rule: PUT을 이용하여 변하는(mutable) 자원을 업데이트한다. Rule: POST를 이용하여 Collection에 새로운 자원을 생성한다. Rule: POST를 이용하여 Controller를 실행한다. - Response header의 Allow 항목에 이용 가능한 Method 목록을 확인할 수 있다. - Collection이나 Store에 있는 자원을 제거하는 데 사용한다. - ‘soft’하게 자원을 제거하거나 state 변경이 필요한 경우, DELETE 대신에 POST를 사용하기도 한다. - 어떤 Controller Resource를 대상으로 POST를 사용한다. - 따라서 POST는 새로운 자원을 생성하는 것 외, 자원을 얻거나(get), 저장(store), 제거(delete) 하는 데 사용하지 않는다. - PUT Request 메시지는 저장하거나 업데이트 하고자 하는 자원을 포함해야 한다. - GET 요청과 같은 Response body를 받을 수도 아닐 수도 있다. - Store 자원 같은 경우에는 변하는(mutable) 자원만 허용하는데, GET 요청은 변하지 않는(immutable) 자원을 요청하기도 하기 때문

Status Code Category Description 1xx: informational Protocol 레벨의 정보를 제공한다. 2xx: Success Client의 요청을 성공적으로 받았다. 3xx: Redirection 요청을 완료하기 위해서 Client가 추가적인 작업을 해야 한다. 4xx: Client Error Client 쪽의 실수를 나타낸다. 5xx: Server Error Server 쪽에서 error를 처리해줘야 한다. Status Code의 분류

Status Code Rule: 200(“OK”)은 성공을 나타내는 데 사용된다. Rule: 200(“OK”)은 Error를 다루는 용도로 사용해서는 안된다. Rule: 201(“Created”)은 자원을 성공적으로 생성했음을 나타낸다. Rule: 202(“accepted”)는 비동기 액션의 성공적인 시작을 나타낸다. Rule: 204(“No Content”)는 응답 메시지의 body가 의도적으로 비어 있다고 알릴 때 사용한다. Rule: 301(“Moved Permanently”)은 자원의 위치가 이전됬음을 나타낸다. - 200 code는 요청 후, 성공적으로 응답을 Client에 전달했다는 의미로 사용된다. - 200 code는 반드시 Response Body를 포함하며, 204 code는 response body가 없다 - Collection이 생성되거나, Store가 추가되면 결과로 201 code를 보낸다. - Client에게 요청은 유효하다고 한다. - 하지만, 최종적으로 그 요청이 처리되기에는 어떤 문제가 있기 때문에 보내주는 code이다. - 예를 들면, 서버가 다른 요청을 다루고 있는 중일 때, 이런 결과를 보낸다. - 요청에 대해서 body는 없다. - 하지만, Header 부분은 의미 있는 정보가 있을 수 있다. - URI가 변경 됬을 경우 보내준다. - Response header의 Location 부분에 변경된 URI를 명시해줘야 한다.

Status Code Rule: 302(“Found”)는 사용하면 안된다. Rule: 303(“See Other”)은 Client에 다른 URI를 알려줘야 한다. Rule: 304(“Not Modified”)는 bandwidth를 유지하기 위해 사용한다. Rule: 307(“Temporary Redirect”)은 Client에게 다른 URI로 요청을 다시 보내라고 할 때 사용한다. Rule: 400(“Bad Request”)는 요청의 실패를 알릴 때 사용한다. - HTTP/1.0에서 사용되었던 302 code는 ”Moved Temporarily”였다. - GET이나 HEAD 요청이 왔을 때, 자동으로 header에 있는 Location으로 GET 요청하도록 되어있다. - 문제는 Client 입장에서 의도치 않게 요청 메소드가 바뀌는 부분이다. - 그래서 HTTP/1.1에서는 대신에 303(“See Other”) or 307(“Temporary Redirect”)를 제공 - 302 code와 다르게 Redirection이 발생하지 않으며, 대신 다른 URI가 Location에 지정되어 제공된다. - 일반적인 Client 측 error - 204 code와 response body가 없다는 점에서 유사 - 하지만, 304 code는 이미 client가 최신 버전의 response를 가지고 있어서 body를 비워두고 보내는 것 - REST API가 Client의 요청 처리를 더 이상 진행하지 않겠다는 의미 - 대신에 Client가 다시 다른 URI로 요청하도록, Client에 임시 URI를 보낸다.

Status Code Rule: 405(“Method Not Allowed”)는 HTTP Method를 지원하지 않을 때 사용한다. Rule: 406(“Not Acceptable”)은 요청한 media type을 처리할 수 없을 때 사용한다. Rule: 409(“Conflict”)는 자원의 상태를 위반했을 때 사용한다. Rule: 401(“Unauthorized”)은 Client의 신용에 문제가 있을 때 사용한다. Rule: 404(“Not Found”)는 Client의 URI가 자원과 맵핑이 실패했을 때 사용한다. Rule: 403(“Forbidden”)은 인가된 상태임에도 불구하고 접근을 금지할 때 사용한다. - 인가(Authorization)없이, 자원에 접근하려고 할 때, 보호하기 위해 사용 - Application 레벨에서의 권한을 요구한다. - 예를 들어 Client가 허용된 범위 밖에서 자원에 접근하려고 할 때, 403 code를 보낸다. - Resource가 허용하지 않는 HTTP Method를 사용한 경우 - Response header의 Allow 항목에 허용하는 HTTP Method를 적어줘야 한다. - Client가 원하는 결과 타입을 보내줄 수 없을 때 (Request header의 Accept 항목) - 예를들어, client는 ‘application/xml’을 원했지만, API는 ’application/json’을 줄 때 - Client가 REST API의 자원(resource)의 상태를 불가능한 형태로 변경하려고 할 때 - 예를 들어 Store의 resource가 비어있지 않은데, 삭제를 요청할 때

Status Code Rule: 412(“Precondition Failed”)는 조건부 operation이 필요할 경우 사용된다. Rule: 415(“Unsupported Media Type”)는 요청 payload의 media type을 처리할 수 없을 때 사용한다. Rule: 500(“Internal Server Error”)은 API가 제대로 작동 안함을 나타낸다. - Client가 요청 시, Request header에 추가적인 조건을 만족하는 정보를 제공할 것을 요구할 때 - 만약 그 추가적인 조건을 만족하지 못했을 경우 412 code를 보낸다. - Client의 Request header의 Content-type이라는 항목에 명시되어 있는 type을 API가 처리할 수 없는 type일 경우 - 일반적인 REST API error 결과이다. - 대부분 웹 프레임워크들이 자동으로 예외가 발생했을 경우 보내주는 code

Thank you!! *