RESTful API 설계 시 URI 명명 규칙과 idempotent 특성 보장 방법

Table of Contents

RESTful API란 무엇인가

RESTful API는 인터넷에서 데이터를 교환하기 위한 아키텍처 스타일 중 하나입니다. REST는 Representational State Transfer의 약자로, 자원을 나타내는 데 초점을 두고 있습니다. RESTful API는 이러한 자원에 대한 상태를 클라이언트와 서버 간에 교환하며, 자원은 URI(Uniform Resource Identifier)로 식별됩니다. 쉽게 말해, RESTful API는 웹 상에서 데이터를 주고받을 수 있게 해주는 일종의 규칙입니다. 이 규칙을 잘 따르면, API가 더 이해하기 쉽고 사용하기 쉬워집니다.

URI 명명 규칙

URI는 자원을 식별하는 데 사용되는 주소입니다. 따라서 명확하고 일관된 규칙을 따르는 것이 중요합니다. URI를 설계할 때는 다음과 같은 규칙을 고려하는 것이 좋습니다.

리소스를 명사로 표현

URI는 리소스를 표현해야 합니다. 예를 들어, ‘사용자’라는 자원을 나타내려면 `/users`와 같은 형식을 사용합니다. RESTful에서는 동사보다는 명사를 사용하여 리소스를 나타내는 것이 일반적입니다.

대소문자 일관성 유지

URI는 대소문자를 구분합니다. 따라서 URI 설계 시에는 소문자를 사용하는 것이 일반적인 관례입니다. 예를 들어, `/users`는 `/Users`와 다르게 인식되므로, 일관되게 소문자를 사용하는 것이 좋습니다.

복수형 사용

컬렉션을 표현할 때는 복수형을 사용합니다. 예를 들어, 여러 사용자를 나타내는 리소스는 `/users`로 표현합니다. 이는 일관성을 유지하며, API 사용자에게 명확한 이해를 제공합니다.

하이픈으로 단어 구분

URI 내에서 여러 단어를 사용할 때는 하이픈(-)으로 구분하는 것이 가장 좋습니다. 예를 들어, `/user-profile`과 같은 형식으로 표현합니다. 하이픈은 단어를 구분하는데 명확성을 제공하며, 읽기 쉽습니다.

Idempotent 특성의 중요성

Idempotent는 연산을 여러 번 수행하더라도 결과가 달라지지 않는 성질을 의미합니다. RESTful API에서는 이러한 특성을 보장하는 것이 중요합니다. 특히, HTTP 메서드 중 GET, PUT, DELETE는 반드시 idempotent해야 합니다. 이는 API 사용자가 같은 요청을 여러 번 보내더라도 시스템의 상태가 변경되지 않거나 동일한 결과를 얻을 수 있음을 의미합니다.

GET 메서드

GET 메서드는 서버의 상태나 자원의 정보를 가져오는 데 사용됩니다. 이 메서드는 서버의 상태를 변경하지 않으므로 항상 idempotent합니다. 예를 들어, `/users/123`에 GET 요청을 여러 번 보내더라도 사용자 정보는 변경되지 않습니다.

PUT 메서드

PUT 메서드는 자원을 업데이트하거나 생성하는 데 사용됩니다. 이때, 같은 요청을 여러 번 보내더라도 결과가 동일해야 합니다. 예를 들어, `/users/123`에 특정 데이터를 PUT 요청하면, 동일한 요청을 여러 번 보내더라도 사용자 정보는 최종적으로 동일하게 유지됩니다.

DELETE 메서드

DELETE 메서드는 자원을 삭제하는 데 사용됩니다. 이 역시 idempotent해야 하며, 여러 번 요청하더라도 자원이 삭제된 상태는 변하지 않아야 합니다. 예를 들어, `/users/123`에 DELETE 요청을 보내면, 첫 번째 요청 후에는 해당 사용자 정보가 삭제됩니다. 이후 같은 요청을 반복해도 상태는 변하지 않습니다.

POST와 Idempotent

POST 메서드는 idempotent하지 않은 메서드로, 서버의 상태를 변경하거나 새로운 자원을 생성하는 데 사용됩니다. 예를 들어, `/users`에 POST 요청을 보내면 새로운 사용자가 생성됩니다. 같은 요청을 여러 번 보내면 사용자가 여러 번 생성되므로, POST는 idempotent하지 않습니다. 이 메서드를 사용할 때는 이러한 특성을 명확히 이해하고 설계해야 합니다.

RESTful API 설계 시 주의사항

RESTful API를 설계할 때는 URI 명명 규칙과 idempotent 특성을 고려하는 것이 중요합니다. 이는 API의 일관성과 안정성을 보장하며, 사용자가 쉽게 이해하고 사용할 수 있도록 도와줍니다. 특히, idempotent 특성을 잘못 구현하면 데이터 무결성이 깨질 수 있으므로 주의해야 합니다. 이러한 규칙과 특성을 잘 지키면, RESTful API는 더욱 효율적이고 신뢰할 수 있는 시스템을 구축하는 데 큰 도움이 됩니다.