웹 개발에서 REST API는 클라이언트와 서버 간 통신을 원활하게 하는 중요한 역할을 합니다.

여기서 클라이언트는 프론트엔드, 서버는 백엔드라고 생각할 수 있습니다.

클라이언트(프론트엔드)와 서버(백엔드)는 서로 직접적으로 호출하기보다는, Application Programming Interface (API)라 불리는 중간자 역할의 인터페이스를 사용합니다.

API는 클라이언트-서버 통신 간 중요한 역할을 하므로, 항상 잘 생각해서 모범사례의 API를 설계해야 합니다. 그래야만 개발자들이 유지보수하기 쉽고, 사용하기 좋을 뿐만이 아니라, 사용하는 동안 문제를 일으키지 않습니다.

이 자료에서는 REST API를 만들기 위한 9가지 모범사례들을 소개할 예정입니다. 잘 따라온다면 여러분들은 사용자들이 사용하기 쉽고, 강력한 API들을 만들 수 있을 것입니다.

그 전에 앞서, REST API란 무엇일까요? REST는 Representational State Transfer의 약자로 해석하면 원하는 리소스를 현재 상태에 걸맞은 형태로 전송하는 것입니다. REST는 2000년에 Roy Fielding이 웹을 위해 디자인한 소프트웨어 아키텍처 형식입니다.

API(Application Programming Interface)는 Restful이라는 REST 디자인 원칙을 따릅니다.

간단히 말하자면, REST API는 두 컴퓨터가 HTTP(Hypertext Transfer Protocol)를 통해 통신할 때, 같은 형식에 맞춰 통신하도록 합니다.

REST API 디자인을 위한 모범사례

1. 데이터를 보내거나 받을 때 JSON 포맷을 사용하세요

예전에는 API 요청을 보내거나 받을 때 XML이나 HTML을 사용했었지만, 최근에는 JSON(JavaScript Object Notation)을 사용하는 것이 추세입니다.

XML은 사용할 때 데이터를 인코딩/디코딩하는 게 번거로울 때가 많아 여러 프레임워크에서 지원하지 않는 경우가 많습니다.

JavaScript는 API를 받아올 때 JSON을 사용하도록 만들어져 있기 때문에 JSON으로 파싱하는 내장 메소드를 가지고 있습니다. Python이나 PHP 같은 다른 프로그래밍 언어들도 요즘은 JSON으로 파싱하거나 데이터를 다룰 수 있는 메소드들을 지원합니다. (예를 들어, Python의 json.loads()나 json.dumps()가 있습니다.)

클라이언트 단(Client-side)에서 JSON 데이터를 정확하게 해석하도록 보장하기 위해서는 요청하는 동안 응답 헤더(Response header)에서 Content-Type 타입을 application/json으로 지정해야 합니다.

반대로 다수의 서버 단(Server-side) 프레임워크들에서는 Content-Type을 자동으로 할당합니다. (예를 들어, Express는 express.json()가 그 기능을 합니다. body-parser 라는 NPM의 패키지도 같은 기능을 합니다.)

2. 엔드포인트에서는 동사 대신 명사를 사용하세요

REST API를 설계할 때는 엔드포인트 주소에 동사를 사용하지 마세요. 이때는 명사를 사용해서 각 엔드포인트들이 무슨 일을 하는지 명시해야 합니다.

HTTP 메소드들이 이미 GET, PUT, PATCH, DELETE라는 동작을 (Create, Read, Update, Delete) 동사의 형태로 나타내기 때문입니다.

GET, POST, PUT, PATCH, DELETE는 가장 주로 쓰이는 HTTP 동사들이고, COPY, PURGE, LINK, UNLINK 등과 같은 다른 것들도 있습니다.

따라서 엔드포인트 주소는 다음과 같아서는 안 됩니다. https://mysite.com/getPosts 혹은 https://mysite.com/createPost 대신에 이런 모습이면 더 좋겠지요: https://mysite.com/posts

요약하자면, HTTP 메소드로 엔드포인트가 무슨 일을 할지 정하도록 하세요. GET은 데이터를 얻어오고, POST는 데이터를 생성하며, PUT은 데이터를 갱신하고, DELETE는 그 데이터를 삭제하도록 합시다.

3. 복수 명사를 사용하세요

API 데이터는 사용자로부터 얻어온 리소스라고도 볼 수 있습니다.

https://mysite.com/post/123와 같은 엔드포인트가 있다면, POST 요청으로 게시물을 지우거나, PUT 혹은 PATCH 요청을 통해 갱신하는 게 가능할 겁니다. 그러나 사용자는 다른 게시물들이 있음을 알아채기 힘들 수 있기 때문에 복수 명사를 사용해야 합니다.

따라서 https://mysite.com/post/123 보다는, https://mysite.com/posts/123이 되어야 합니다.

4. 에러 핸들링을 위해 상태 코드를 사용하세요

API 요청에 대해 응답할 때는 항상 HTTP 상태 코드를 포함해야 합니다. 그래야만 사용자가 요청이 성공했는지, 실패했는지 등 어떻게 돌아가는지 알 수 있습니다.

다음은 HTTP 상태 코드들과 의미를 담은 표입니다.

5. 관계를 보여주기 위해 엔드포인트를 중첩해 사용하세요

종종 다른 엔드포인트들은 연결되곤 합니다. 따라서 이해하기 쉽도록 중첩해 사용하세요

멀티 유저 블로그 플랫폼의 경우를 예로 들자면, 여러 게시물이 각기 다른 사용자들에 의해 작성됩니다. 따라서 엔드포인트를 https://mysite.com/posts/author 만들면 됩니다.

같은 식으로, 게시물들은 각자의 댓글들을 가지고 있기 때문에 댓글을 받아오는 엔드포인트는 https://mysite.com/posts/postId/comments 정도면 될 것 같습니다.

그렇다고 3단계 이상을 중첩하면 가독성이 떨어지기 때문에 너무 많이 중첩하지 않는 것이 좋습니다.

6. 데이터를 받을 때 필터링, 정렬, 페이지를 나누세요

API의 데이터베이스가 엄청나게 클 때가 있습니다. 그럴 때는 데이터베이스에서 데이터를 받아올 때 느려질 수가 있습니다.

필터링, 정렬, 페이지 나누기를 통해 필요한 데이터만 걸러내어 요청에 대한 부담을 줄일 수 있습니다.

필터링된 엔드포인트를 예시로 들자면 다음과 같습니다. https://mysite.com/posts?tags=javascript 이 엔드포인트는 JavaScript 태그를 가진 게시물들을 받아옵니다.

7. 보안을 위해 SSL을 적용하세요

SSL은 전송 계층 보안(Secure Socket Layer)을 나타내며, REST API 설계의 취약점을 줄이고 의심스러운 공격을 예방하는 보안에서 중요한 요소입니다.

서버와 클라이언트 사이를 비공개하고 요청한 것만큼의 데이터만 보내주는 것도 고려해야 합니다.

SSL 인증서는 등록하기 어렵지 않고, 대부분 첫 일 년은 무료입니다. 유료인 경우에도 비싼 편은 아닙니다.

REST API에서 SSL을 적용한 것과 적용하지 않은 URL에서 차이는 HTTP에 "s"의 유무입니다. https://mysite.com/posts는 SSL을 적용한 것이고, http://mysite.com/posts는 SSL을 적용하지 않은 것입니다.

8. 버전을 명시하세요

REST API는 여러 버전을 지원해서 사용자들이 최신 버전이 아니더라도 사용할 수 있게 해야 합니다. 최신 버전만 지원하게 되면, 부주의하게 버전을 올릴 시 애플리케이션에 영향을 미칠 수 있습니다.

웹 개발에서 가장 흔한 버전 관리 방법은 Semantic Versioning입니다.

Semantic versioning의 한 예는 1.0.0, 2.1.2, 3.3.4 등이 있습니다. 첫 번째 숫자는 주 버전을 의미하며, 두 번째 숫자는 부 버전을 의미하고, 세 번째 숫자는 패치 버전을 의미합니다.

큰 기업부터 개인 서비스까지 RESTful API들은 다음과 같이 제공됩니다. 버전 1 : https://mysite.com/v1/ 버전 2 : https://mysite.com/v2/

페이스북은 자사 API를 다음과 같이 버전 관리합니다.

스포티파이는 다음과 같이 제공합니다.

버전 관리에 있어 모든 API들이 위와 같이 하는 건 아닙니다. 메일침프는 좀 다르게 표기합니다.

이런 방식으로 REST API를 설계하면 사용자들이 자신의 선택에 따라 버전을 사용할 수 있습니다.

9. 정확한 API 문서를 제공하세요

REST API를 제작할 때, 사용자들이 쉽게 배울 수 있고 정확하게 사용할 수 있게 해야 합니다. 가장 좋은 방법은 API에 대한 좋은 문서를 제공하는 것입니다.

문서는 다음 내용들을 포함해야 합니다.

• 해당 API에 대한 엔드포인트
• 해당 엔드포인트에 대한 요청 예시
• 다양한 언어 지원
• 각 상태 코드에 대한 다른 에러 메시지 리스트

가장 흔히 사용하는 API 문서 툴은 Swagger입니다. API 테스트의 경우 Postman을 자주 사용합니다.

결론

이 문서에서 독자는 REST API를 설계할 때 명심해야 할 모범 사례들을 배웠습니다.

이 모범 사례들과 규칙들을 잘 실천해야 잘 작동하고 안전하며 API 사용자들이 손쉽게 사용할 수 있는 애플리케이션을 구축할 수 있습니다.

읽어주셔서 감사하며 앞으로는 API들을 해당 모범사례들을 적용해 만들어주시기를 바랍니다.