RESTful API의 설계규칙

RESTful API란? 

 

RESTful API는 Representational State Transfer(표현 상태 전이)의 약자로, 자원을 이름(URI)으로 구분하여 해당 자원의 상태를 주고받는 API 설계 방식을 말합니다.

 

왜 RESTful API를 사용할까?

 

이러한 규칙을 지켜서 API를 설계하면, API의 가독성과 유지 보수성이 향상되며, API 사용자들도 보다 쉽게 API를 이해하고 사용할 수 있습니다.

 

 

RESTful API의 설계규칙

 

RESTful API 설계 시 지켜야 할 규칙에 대해 알아보겠습니다.

1. URI는 정보의 자원을 표현해야 합니다. RESTful API에서는 URI가 자원을 표현하는 데 중요한 역할을 합니다. URI는 해당 자원을 고유하게 식별할 수 있도록 표현해야 합니다. 예를 들어, /users는 모든 사용자를 나타내며, /users/1은 ID가 1인 사용자를 나타냅니다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현합니다. HTTP Method는 자원에 대한 CRUD(Create, Read, Update, Delete) 작업을 수행합니다. GET은 자원을 조회할 때, POST는 자원을 생성할 때, PUT은 자원을 수정할 때, DELETE는 자원을 삭제할 때 사용합니다.
3. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용합니다. 슬래시 구분자는 계층 구조를 표현할 때 사용합니다. 예를 들어, /users/1/comments는 사용자 ID가 1인 사용자의 댓글을 나타냅니다.
4. URI 마지막 문자로 슬래시(/)를 포함하지 않습니다. URI 마지막 문자로 슬래시를 포함하면, 리소스에 접근할 때 불필요한 리디렉션을 발생시킬 수 있습니다. 따라서, URI 마지막 문자로 슬래시를 포함하지 않는 것이 좋습니다.
5. 하이픈(-)은 URI 가독성을 높이는 데 사용합니다. URI에 하이픈을 사용하면, 가독성을 높일 수 있습니다. 예를 들어, /users/1/comments/2는 /users/1/comments/2와 같이 표현할 수 있습니다.
6. 언더바(_)는 URI에 사용하지 않습니다. 언더바는 가독성을 떨어뜨리기 때문에, URI에서는 사용하지 않는 것이 좋습니다.
7. URI에는 소문자를 사용합니다. URI는 대소문자를 구분하기 때문에, URI에는 소문자를 사용하는 것이 좋습니다. 대문자를 사용할 경우, URI를 잘못 입력한 경우에도 오류가 발생할 수 있습니다.

 

RESTful API 설계 시 주의사항

 

RESTful API 설계 시 다음과 같은 사항에도 주의해야 합니다.

1. URI에는 동사보다는 명사를 사용합니다. URI에는 자원을 나타내는 명사를 사용하는 것이 좋습니다. 동사를 사용할 경우, URI가 어떤 동작을 수행하는지 알기 어려울 수 있습니다.
2. URI에는 CRUD 동작을 나타내는 단어를 사용하지 않습니다. RESTful API에서는 HTTP Method를 이용하여 자원에 대한 CRUD 작업을 수행하므로, URI에는 이러한 동작을 나타내는 단어를 사용하지 않습니다. 예를 들어, /users/create는 올바르지 않은 URI입니다.
3. 복수형 명사를 사용합니다. 리소스에 대한 URI를 설계할 때는 복수형 명사를 사용하는 것이 좋습니다. 예를 들어, /users와 같이 복수형 명사를 사용하는 것이 좋습니다.
4. HTTP 응답 코드를 잘 활용합니다. HTTP 응답 코드는 API의 성공, 실패 여부를 나타내는 중요한 역할을 합니다. 따라서, 적절한 HTTP 응답 코드를 사용하여 API의 성공, 실패 여부를 명확하게 알려주는 것이 좋습니다.