자원을 나타내는 유일한 주소 HTTP (The HyperText Transfer Protocol) - HTML 문서와 같은 자원들을 가져올 수 있도록 해주는 프로토콜 HTML (HyperText Mark-up Language) - 웹 페이지를 만들기 위한 언어 REST (Representational State Transfer) - 월드 와이드 웹(www) 과 같은 소프트웨어 아키텍처의 한 형식 - 자원을 정의하고, 자원에 대한 주소를 지정하는 방법 전반을 뜻한다. API (Application Programming Interfaces) - 응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페 이스 - 예를 들어, 파일 제어, 창 제어, 문자 제어 등
인터넷에서 기술을 구현하는 필요한 상세한 절차, 기본 틀 등을 제공하는 공문서 간행물 배경 웹 표준 정의 - 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는 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를 구현한 것이다.
자원의 위치 - 웹 상에 서비스를 제공하는 각 서버들에 있는 파일의 위치를 표시하기 위한 것 - 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
"?" query ] [ "#" fragment ] - URI를 어떤 규칙에 따라 기술하고 자원(데이터)에 어떻게 접근하는지 지정 - http, ftp … - 서버명과 도메인명으로 구성 - 서버명 – www, api, develop … - 도메인명 – test.co.kr - 폴더명과 파일명으로 구성 - 서버 내부 자원의 위치를 나타낸다.
계층 관계를 나타내기 위해 사용되어야 한다. 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에서 사용되면 안 된다.
때문에 편리하게 소문자를 선호한다. 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에서 파일확장자는 포함되어서는 안된다.
번째 서브도메인의 이름은 서비스가 무엇인지 구분할 수 있는 것이어야 한다. 예를 들어 API의 풀 도메인은 서브도메인으로 "api"를 붙여야 한다. http://api.soccer.restapi.org Rule: API에는 일관된 서브 도메인 이름이 사용되어야 한다. Rule: 마찬가지로 개발자 포탈에도 일관된 서브 도메인 이름이 사용되어야 한다. 대부분의 REST API는 관련 웹사이트를 가지고 있다. 개발자 포털 -> 문서, 포럼, API access key를 제공 등등 마찬가지로 "developer"라는 서브 도메인을 붙여주어야 한다. http://developer.soccer/restapi.org
리소스 모델링하는 것은 비슷I - leagues -> seattle -> teams -> trebuchet - 이런식으로 REST API의 경우에도 리소스를 계층적으로 구성한다는 것이 유사 http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
가진다. 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
사용되어야 한다. 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)
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개의 데이터를 받겠다는 의미
Rule: GET을 이용하여 자원을 얻는다. - Jsonplaceholder라는 REST API 요청 테스트 사이트로 cURL 날린 결과 (curl은 기본적으로 GET 요청을 한다.) - Resonpse body - HTTP Status Code - Reqeust Line (Get 요청이 사용되었음을 나타냄)
해서는 안된다. - 터널링? 다른 용도로 오,남용 한다는 의미 - 즉, GET과 POST는 Resource를 얻거나 생성하는 용도로만 사용해야 한다. Rule: HEAD를 이용하여 Response의 Header 정보를 얻는다. - CURL의 “head” 옵션을 이용하여 header 정보를 얻을 수 있다.
자원의 이용 가능한 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) 자원을 요청하기도 하기 때문
2xx: Success Client의 요청을 성공적으로 받았다. 3xx: Redirection 요청을 완료하기 위해서 Client가 추가적인 작업을 해야 한다. 4xx: Client Error Client 쪽의 실수를 나타낸다. 5xx: Server Error Server 쪽에서 error를 처리해줘야 한다. Status Code의 분류
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를 명시해줘야 한다.
다른 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를 보낸다.
때 사용한다. 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가 비어있지 않은데, 삭제를 요청할 때
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
chanyounglee
nrslib
iwatatomoya
alexanderschranz
hollycummins
kentaroutakeda
karugamo
andpad
kubotak
soyuka
tanakahisateru
yusukebe
yue4u
bkeepers
sonatard
garrettdimon
hannesfritz
jonyablonski
ammeep
tammyeverts
aki_iinuma
deanohume
speakerdeck
samanthasiow
rocio
