(번역)REST : Good Practices for API Design

 

REST: Good Practices for API Design

 

요즘 회사에서 api 개발을 하는데 좀 더 보기 좋고 효율적인 API 만드는 방법이 뭐가 있을 까 고민하다가 검색을 통해 몇개의 블로그들을 봤는데 영어 공부도 할겸 REST: Good practices for API Design 글을 번역을 하였습니다. 그냥 독해하면 되지 않을까 하는 생각으로 접근하였는데 막상 번역을 할려고하니 어렵네요.. 

 

이 글에서 나오는 용어 정리를 해보면 

 

• Resouce : 어떤 것의 대표 혹은 객체 ex) employees , animals 
• Collections: resouces 의 집합 
• URL:  어느 resource 가 어디에 위치할 수 있고 , 어떤 action들이 수행될 수 있는지를 나타내는 경로 

 

REST 가 무엇인가?

 

2000년에 HTTP 사양의 주요 저자중 한명인 Roy Fielding 가 Representational State Transfer(REST)라고하는 웹 서비스를 설계하기 위한 아키텍처 접근 방식을 제안했다. 

이 기사는 HTTP 프로토콜 사용하여 REST 를 구현한다고 가정하지만 REST 는 HTTP에 연결되어 있지 않다.

REST API는 엔티티 또는 서비스가 될 수 있는 '리소스'에 대해 구현됩니다. 

이러한 API는 HTTP를 통해 자원의 현재 상태 표현을 전송하는 데 사용할 수 있는 URI로 자원을 식별하는 방법을 제공합니다. 

 

왜 API 디자인이 중요한가?

 

사람들은 이 질문을 많이하고 이렇게 대답한다. 

 

REST API는 어떤 서비스의 표면이고 그러므로 그것들은 

 

1. 통합이 간단하기 위해서 이해하기 쉽게

2. 문서화를 잘하자.

3. HTTP 표준을 따르자.

 

 

REST API 개발하고 디자인하기

 

REST API를 디자인할때 몇개의 규약이있다 .

 

다음은 우리가 따르는 규약이다.

 

 

1. URI 명사를 사용하자.

 

REST API는 엔티티 또는 서비스가 될 수 있게 리소스를 위해 디자인 되어야한다. 그러므로 그것들은 항상 명사로 해야한다.

 

예를 들면 /createUser 대신에 /users 

 

 

2. 복수 또는 단수 

 

일반적으로, 우리는 복수형으로 사용하는걸 선호하지만 단수형에 대해서는 딱딱한 규칙이 없다.

 

GET /users/123

 

클라이언트는 id 123 가진 유저 객체로부터 리소스를 회수 요청을한다.

리소스가 만들어지는 동안에 우리는 현재 리소스의 컬렉션을 추가하기를 원한다. 

그래서 api는 아래와 ..

 

POST /users

 

 

3. HTTP  액션 정의 

 

API는 리소스의 명사를 제공해야하고 HTTP 동사를 정의해한다.

 

아래 테이블은 HTTP 동사를 요약

 

 

4. 안전한 메소드를 악용하지 말것 

 

안전한 메소드는 클라이언트가 호출 횟수와 관계없이 동일한 리소스 표현을 반환하는 HTTP 메소드이다.  

GET,HEAD,OPTIONS 과 TRACE 메소드는 안전으로 정의된 메소드이다. 그것들은 데이터를 리턴하는할 용도로만 사용되며 서버의 리소스의 상태를 변화해서는 안된다. GET 을 사용하여 컨텐츠를 삭제하지마라.

 

예를 들면 

 

GET /users/123/delete 

 

수행해야 할 작업에 따라 HTTP 메소드를 사용해라. 

 

5. URI 를 통해서 리소스 계층을 묘사한다 . 

 

만약 리소스가 서브 리소스가 포함되면 더 명확하기 위해서 API 에서 이것을 명시해야한다. 

예를 들면 만약 사용자가 posts를 가지고 있으면 우리는 사용자의 특정 post를 리턴해야하다면,

API는 GET /users/123/posts/1(id 가 123 를 가진 유저의 포스터가 1인 것을 리턴 ) 

 

 

6. 너의 API 버전관리 

API의 버전관리는 새로운 기능을 추가하거나 새로운 클라이언트에 대한 기존 기능을 업데이트하면서 서비스의 이전 번전과의 호환성을 보장합니다. 대부분 아래에 두개의 범주에 속합니다.

 

Headers :

 

headers 안에 버전을 명시할 수 있는 2가지 방법이 있다. 

 

Customer Header : 

사용자 X-API-VERSION 헤더 키를 추가하여 올바른 엔드포인트로 요청 할 수 있게 한다. 

 

Accept Header :

너의 버전을 accept header 를 이용하여 명시한다 

=> Accept : application/vnd.hashmapinc.v2+json 

 

URL :

URL 에 버전을 적는다 

 

POST /v2/users 

 

우리는 버전관리를 위해 URL 메소드를 사용하는것을 선호한다. 그것은 URL 보는것에 의해 리소스를 더 차별화를 준다. 

 

7. 표현을 리턴

 

 리소스를 생성하거나 리소스에 필드를 업데이트하는  POST, PUT or PATCH methods는 항상 

적절한 상태 코드 응답으로 업데이트된 리소스 표현을 리턴해야한다. 

 

만약 새로운 리소스를 성공적으로 추가하면  HTTP 상태 코드 201이 Location header에 새로 생성된 리소스 URI와

함께 반환되어야 한다. 

 

8. 필터 , 검색 과 정렬

 

필터링, 검색 또는 정렬 파라미터를 가지고 리소스 가져오기위해 다른 URl 를 만들지마라. 

URI 간단한게 유지하고 쿼리 파라미터를 추가를 시도해라.  

 

 

Filtering : 

 

서버로 부터 리소스를 필터링 위해 URL 안에 쿼리 파라미터 정의된것을 사용해라.  

예를 들면 만약 우리가 user 의 모든 posts들을 가져온다면 

 

GET /users/123/posts?state=published 

->state가 필터 파라미터이다. 

 

Searching:

 

기본 필터 대신에 강력한 검색 쿼리 결과를 얻기 위해 한가지는 서버로 부터 리소스를 가져오기위해 

URI에 여러 파라미터를 사용해라 

 

GET /users/123/posts?state=published&ta=scala 

-> scala 태그를 공개하는 posts를 검색한다. 

 

GET /users/123/posts?q=sometext&fq=state:published,ta:scala 

-> 이것은 scala 태그를 가지고 있고 공개된 상태에서 fq 가 state 를 필터하고 sometext를 검색하는걸 의마한다.  

 

Sorting : 

 

ASC and Desc 정렬 파라미터들은 URL에 명시한다.

 

GET /users/123/posts?sort=-updated_at 

->업데이트된 posts를  내림차순으로 정렬한다 .

 

 

9. 인증

 

REST API 는 stateless 해야한다. 모든 요청은 자급 자족해야하며 이전 요청에 대한 지식 없이도

충족되어야 한다. 이는 사용자 인증 경우에 발생한다. 

 

이전에 개발자들은 확장 가능한 접근이 아닌 서버 사이드 세션에 유저 정보를 저장했다.

이러한 이유로 모든 요청은 유저의 모든 정보를 포함해야한다 .

이것은 서비스 간 인증을 허용하기 때문에 인증된 사용자로 API를 제한하지 않는다. 

 

사용자의 인증을 위해서 OAuth2 가 포함된 JWT(JSON Web Token)  이것들을 달성할 방법을 제공한다. 추가적으로 서비스 서비스간 통신의 경우 헤더에 암호화된 API-key 키가 전달되로록 하면된다.  

 

 

10. 문서화 

 

swagger  REST API를 문서화하는데 폭넓게 사용되는 툴이다.

개발자가 근본적인 동작을 이해하게 해준다. 주석을 사용하여 문서를 추가하는 방법으로 

API 및 용도를 설명하는 JSON 을 생성한다.  

 

 

11. HTTP 상태코드 

 

클라이언트에게 응답을 제공하기 위해 HTTP 상태코드를 사용한다.

그것은 성공 또는 실패 반응을 제공해주지만 서버관점에서 성공 실패 의미를 명확하게 정의해야한다. 

 

2XX Success 

 

200 ok:  GET or DELETE  성공 리턴, PUT or POST 는 이것을 사용할 수 있다.

 

201 Created : POST 요청에 의해 성공한 리소스 

 

3xx Redirection 

 

304 Not Modified: HTTP 캐싱 헤더가 사용된 경우 

 

4XX Client error 

 

400 Bad Request : 요청 자체가 잘못되었을때 사용하는 코드이다.

 

401 Unauthoried : 인증이 실패한 경우 .

 

403 Forbidden :  정보가 맞지만  유저가 요청에 승인되지 않는 경우  

 

404 Not Found :   요청된 리소스가 서버에서 이용할 수 없는 경우( 찾는 리소스가 없다는 뜻 )

 

405 Method Not Allowd: 허용되지 않는 메소드로 요청시 사용하는 경우 

 

5XX Server Errors 

 

이 에러는 서버실패 또는 근본적인 인프라  이슈