[Network] API URI 설계

API란?

API(application programming interface)

• 프로그램들이 서로 상호작용하는 것을 도와주는 매개체
• 애플리케이션이 어떤 프로그램이 제공하는 기능을 사용할 수 있게 만든 매개체

서버가 제공하고자 하는 데이터&기능을 '제어 가능한 API'로 만들면, 접근 권한이 있는 프로그래머&프로그램이 API를 통해 데이터를 요청하여 사용할 수 있다

WEB API

웹에서의 통신을 기반으로 한다

HTTP API

HTTP를 통신 방식으로 사용하는 API

REST API

HTTP API에 다음 4가지 제약조건이 추가된 것

• 자원의 식별

  • 리소스가 요청에서 식별되어야 한다. ex) URI

• 표현(메시지)를 통한 리소스 조작

  • HTTP의 메서드로 POST는 등록 / GET은 조회 같이 리소스를 변경이나 삭제 그리고 조회할 수 있게끔 해야 한다

• 자기서술적 메시지

  • 각 메시지는 자신을 어떻게 처리해야 하는지에 대한 충분한 정보를 포함해야 한다. 예를 들어 단순한 text라면 text/plain, JSON이라면 application/json 이렇게 다양한 양식들을 구분하여 서버에게 정확히 알려주어야 한다는 것

• 애플리케이션의 상태에 대한 엔진으로서 하이퍼미디어

  • 클라이언트가 관련된 리소스에 접근하기를 원한다면 응답 데이터에 링크가 포함되어 있어야한다

이 원칙을 완벽하게 지키며 개발하는 것이 RESTful API 이며, 실무에서 이 방법으로 개발하는 것은 현실적으로 어렵다고 한다.

또한 이미 많은 사람들이 해당 조건을 지키지 않아도 REST API라고 하기 때문에, HTTP API와 REST API를 거의 같은 의미로 사용하고 있다고 한다.
참고

URI 설계시

' 리소스 자체를 식별 ' 하는 것이 가장 중요하다

ex) 회원 정보 관리 API 설계

회원 목록 조회 /read-member-list
회원 조회 /read-member-by-id
회원 등록 /create-member
회원 수정 /update-member
회원 삭제 /delete-member

여기서 '회원등록', '회원삭제'가 리소스가 아니라 '회원' 자체가 리소스이다

• 리소스와 해당 리소스를 대상으로 하는 행위 분리
• 계층 구조로 설계, 복수 단어 사용 권장

변경해보면

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

👉 여기서 행위를 구분하기 위해 HTTP 메소드를 사용한다

회원 목록 조회 GET/members
회원 조회 GET/members/{id}
회원 등록 POST/members/{id}
회원 수정 PUT/members/{id}
회원 삭제 DELETE/members/{id}

그 외에도 다양한 작성 규칙들이 있다

참고
https://bentist.tistory.com/37
https://dev-coco.tistory.com/97
https://ko.wikipedia.org/wiki/REST
https://aws.amazon.com/ko/what-is/api/
https://maenco.tistory.com/entry/HTTP4-API-%EA%B7%B8%EB%A6%AC%EA%B3%A0-REST-API