HTTP API 설계 방법

HTTP API 설계 방법

1. HTTP API는 설계시 항상 리소스 식별을 기준으로 삼아야한다.
2. 위 예시에서 리소스는 게시글이다.
3. URI에 들어갈 리소스는 단수 형태가 아닌 복수 형태로 사용을 권장한다. board → boards
4. URL에 동사를 사용하지 않는다.
5. HTTP Method의 역할을 URL에 포함하지 않는다.

RESTFUL API

1. 리소스는 명사를 사용해야 한다.
2. 단수가 아닌 복수 형태를 사용해야 한다.
3. 만약, REST만으로 해결하기 어려운 경우라면 동사를 허용한다.
4. 자원의 계층 관계를 슬래시(/)로 표현한다.
5. 마지막 문자에는 슬래시(/)가 있으면 안된다.
6. 언더바(_)가 아닌 하이픈(-)을 사용해야 한다.
7. 소문자를 사용해야 한다.
8. URI에 파일 확장자를 포함하면 안된다.
9. CRUD 함수명은 사용하지 않고, HTTP Method를 활용해야 한다.
10. 정렬, 필터링, 페이징은 신규 API를 만드는것이 아닌 Query Parameter를 사용해야 한다

성숙도 모델
Lv 0 - 웹 서비스를 제공하기 위해 URL만 매핑해 놓은 상태

Lv 1

• 외부로 공개하려는 리소스에 대해서 의미있는 URL로 표현하기 시작한 단계
• 적절한 패턴을 가지고 작성 되었지만 HTTP의 메소드 별로 서비스를 구분하여 사용하고 있지는 않다.
• 즉, 서비스 형태나 작업의 종류에 맞추어 적절한 HTTP 메소드를 지정하고 있지 않다.
• 사용자의 요청을 GET, POST로 대부분 처리하고 에러를 반환한다.
• 요청 예시(리소스에 대해 분리된 엔드포인트를 가진다)

Lv 2

• 우리가 제공하고자 하는 리소스를 적절하게 용도와 상태에 따라서 HTTP Methods에 맞게 설계하고 서비스하는 단계.
• 만약 리소스의 상태가 읽기 용도로 사용되는 데이터라고 한다면 GET Method를 사용한다.
• 새로운 리소스를 추가하는 경우는 POST Method
• 기존 리소스의 상태를 변경하기 위해서는 PUT, PATCH Method
• 리소스를 삭제하고자 할 때에는 Delete Method를 사용하여 서비스의 상태를 표현한다.
• RESTful Service의 DB에 저장된 리소스를 확인하고 이러한 데이터를 조작하기 위해서 CRUD와 매칭되는 HTTP Methods를 이용하여 서비스 하는 것을 Level2 단계라고 한다.
• HTTP의 메소드를 이용하여 리소스의 상태를 구분하여 서비스 하게 되면 비슷한 이름의 URI라 하더라도 HTTP Method에 따라서 다른 형태의 서비스를 제공할 수 있게 된다.
• 요청 예시(HTTP Method 활용)

Lv 3

• 데이터를 가지고 그 다음 작업에서 어떠한 작업을 할 수 있는지 상태 정보를 함께 넘겨준다.
• 클라이언트 측에서는 서버가 제공하는 서비스를 일일이 찾는 수고를 겪지 않아도 된다.
• 엔드포인트만 가지고 있으면 서버가 제공할 수 있는 다음, 그 다음 URI값을 알 수 있다.

RESTful API 설계 시 고려해야 할 사항들

1. Consumer first

• 개발자 중심의 설계방식보다 해당 API의 소비자 입장에서 간단하고 직관적인 API를 설계 해야한다.
• 위에서의 소비자는 엔드유저가 아닌 API를 사용 하고있는 또다른 시스템, 개발자 등을 얘기한다.

2. Make best use of HTTP

• HTTP Method와 Request, Response, Header와 같은 HTTP의 장점을 살려서 개발 해야한다.

3. Request methods

• 최소한 성숙도 모델 Level2로는 사용하여야 한다.

4. Response Status

• 각각의 API 요청에 따라서 적절한 HTTP 상태코드가 전달되어야 한다.
• 성공했다, 실패했다가 아닌 왜 실패하고 성공 하였는지 함께 반환 시켜주어야 한다.

*5. No secure info in URI

• URI에는 사용자의 정보를 포함해서는 안된다.

6. Use plurals

• 제공하는 데이터에 대하여 단수가 아닌 복수형태로 쓰는것이 일반적이다.
• 특정 유저를 찾고자 한다면 엔드포인트에 값을 추가한다.

ex) /user -> /users

ex) /users/1

7. User nouns for resources

• 모든 리소스는 가능하면 동사가 아닌 명사형태로 표시한다.
• API URI만 보고도 어떠한 API인지 파악할 수 있는것이 좋다.

8. For exceptions - define a consistent approach

• 일괄적인 엔드포인트를 사용하는것이 좋다.