API URI 설계와 HTTP 메소드

URI를 설계할때의 방법을 알아보자. 

예를 들어 회원 조회, 등록, 수정, 삭제 기능을 만든다고 가정해보자 

이때 URL은

• 조회 /read-member/{id}
• 등록 /create-member/{id}
• 수정 /update-member/{id}
• 삭제 /delete-member/{id}

 

이러한 방법을 이용한다. 하지만 정말 이러한 방법이 좋은 URI 설계일까? 아마 아닐 것이다.

URL을 설계할때 가장 중요한것은 리소스 식별이다. 우리는 URI(Uniform Resource Identifier)라는 것을 잊지 말아야한다.

 

이때 리소스의 의미에 알고 있어야한다. 위와 같이 read, create ,update, delete와 같이 행위를 리소스라 하는게 아니다.

바로 member라는 회원이라는 개념 자체가 리소스이다.  또 다른 예시로 차량을 타다. 차량을 폐차시키다. 차량을 보다

이런 것 중 차량 즉 명사를 지칭하는 단어 들이 대체로 리소스라고 한다.

 

그래서 말하자면 URI를 설계할 때에는 리소스만 식별을 한다.

 

그래서 다시 위의 CRUD URL를 재 설계하자면

• 조회 /members/{id}
• 등록 /members/{id}
• 수정 /members/{id}
• 삭제 /members/{id}

• 참고 : 멤버(회원정보)는 여러명 이기 떄문에 복수단어 사용 권장(members)

이런 형태로 다시 만들 수 있다. 그런데 딱보면 위 상황보다 URL이 간소하고 직관적이지만 문제점이 있다.

바로 기능이 뭔지를 알 수가 없다! 다시 말하자면 조회, 등록, 수정, 삭제같은 행위를 알 수가 없다!

 

어떻게 알 수 있을까? 행위에 대한 구분을 짓기 위해 사용되는 것이 HTTP 메서드이다. 

 

HTTP 메소드

HTTP 메소드는 여러 가지가 있지만 우리가 가장 많이 사용하게 될 주요 메소드에 대해 알아보자 

• GET: 리소스 조회
• POST: 요청 데이터 처리, 주로 등록에 사용
• PUT: 리소스를 대체, 해당 리소스가 없으면 생성
• PATCH: 리소스 부분 변경
• DELETE: 리소스 삭제

이런 주요 메소드 들이 있고 이런 행위들은 HTTP 응답메시지에 표시되어 전송된다. 차례대로 알아보자

GET

GET은 리소스를 조회하는 메서드이다.

 

클라이언트에서  GET(조회)를 통해 members/100(id)의 정보를 조회한다고 요청한다.

 

서버는 members/100의 정보를 json의 형태로 클라이언트에게 전송해준다.

 

POST

POST는 요청 데이터를 처리하는 역할을 한다. 주로 등록에 사용한다. 이때 메시디 바디를 통해 서버로 요청 데이터를 전달한다. 

 

POST(등록) 을 통해 /members(회원)을 등록한다 json형태로 회원정보를 등록요청한다.

그러면 서버에서는 POST를 보고 회원정보를 수집해 서버에 등록한다. 이때 식별자를 서버에서 자동 생성한다. 그 후 다시 회원 정보를 생성했다는 코드와 정보, 식별자 등을 전송한다. 

 

 

PUT

PUT의 기능은 간단히 표현하면 덮어쓰기 이다. 우리가 특정 파일을 폴더에 넣으려고 했을때 같은 이름이 존재하면 덮어쓰기하고 아니면 새로 추가되는 형식인데 이는 PUT형태와 같다. 

 

그리고 POST와도 등록하는 형태가 유사한데 둘의 가장 큰 차이점은 POST는 식별자를 서버에서 생성하고 PUT은 클라이언트가 식별을 이미 한 상태에서 요청하는 것이다.

 

하지만 유의사항이 있다. PUT은 말그대로 덮어쓰기를 하기 때문에 정보의 부분만 변경을 할 수가 없다. 즉 말해서 게시판 글을 수정하는 것 처럼 전체정보를 덮어써야한다. (비밀번호 변경과 같은 기능이 안됨) 그래서 사용하는것이 PATCH이다.

PATCH

PATCH는 리소스의 일부분만 변경할 수 있다.

그림을 보면 PATCH라는 명령에 식별자와 age:50이라는 정보만 들어가 있다.  members/100의 실제 정보는 username, age가 있다.

결과적으로는 age의 20이 50으로만 변경되고 그 외에는 변경 된 것이 없다. 

이게 만약 PUT이었다면 username정보가 사라지고 오롯이 age:50이라는 정보만 등록이 됐을 것이다. 

즉 PATCH는 리소스의 정보를 수정 할 때 사용한다.

 

DELETE

DELETE는 이름 그대로 리소스의 삭제를 요청하는 것이다. 

 

DELETE(리소스 삭제 해줘) /members/100 (식별자 100인 회원정보를) 이라 해석하고 서버는 이를 받아 그림 우측상단에 있는 members/100의 회원정보를 삭제한다. 

 

 

이렇게 HTTP 주요 메소드 들에 알아보았다. 이 메소드들의 특징이 또하나 있다.  안전, 멱등, 캐시라는 속성이고 간단하게 알아보자

 

HTTP 메소드의 속성

안전

호출을 해도 리소스를 변경하지 않는다.  한마디로 GET(조회)을 하게 되면 리소스를 호출을 아무리 해도 정보를 변경하지 않기 때문에 안전하다. (리소스만)

 

멱등

멱등의 뜻은 한번 호출하든 두번 하든 100번하든 결과가 똑같다는 말이다 .

• GET(조회)를 아무리해도 결과는 변경되지 않는다. 그러므로 멱등이 성립한다.(0)
• PUT(덮어쓰기)도 마찬가지로 처음 덮어쓰면 똑같은 요청을 해도 계속 같은 정보가 덮어지기 때문에 멱등이 성립(O)
• DELETE(삭제)도 한번 삭제하면 삭제할 정보가 없어 삭제가 안되 멱등이 성립한다(O)
• POST(등록)은 요청을 여러번 즉 회원 생성 요청을 10번하면 10개의 정보가 생길 수 있기 때문에 멱등이 불성립한다(X)

이 멱등은 서버가 timeout 등의 문제로 정상 응답을 못주었을때, 클라이언트가 같은 요청을 다시 해도 되는가의 판단근거로 쓰인다. 

 

캐시가능

응답 결과 리소스를 캐시해서 사용해도 되는가? 를 본다 .

GET, HEAD, POST, PATCH는 캐시가 가능하다. 하지만 실제로는 GET, HEAD 정도만 캐시로 사용하다. 그 이유는 나머지는 구현이 쉽지 않아서 라는 이유다.

 

---

사실 이 정보들을 공부하면서 RESTful API라는 것이 무엇인지도 함께 알아보았는데 대한민국의 저명한 개발자의 말을 인용하자면 소개한 http api와 restful api는 비슷한다고 한다.(명사, 비연결성, stateless 등) 하지만 HTTP API에서 제약조건이 조금더 들어간 것 들이라 한다. 그리고 restful api를 완벽하게 구현하기는 매우매우 어렵다고 한다.

 

일단 uri의 설계와 http 메소드에 대해 어느정도 알아보았고 웹개발을 할때 유용한 지식을 얻은 것 같다.