API 명세서와 협업

🎦영상 내용 정리

백엔드와 프론트엔드는 API 명세서 를 통해 의사소통을 하고 협업을 한다.

1. API Documentation 구조

1. 이름 및 설명

- 이름: 장바구니에 상품 추가
- 설명: 로그인한 사용자의 장바구니에 1개의 상품을 추가합니다.

2. 기본 정보

- 엔드포인트 : /carts/products/${productId}
- HTTP 메서드 : POST 

3. Request

- Header : Authorization: Bearer{JWT_TOKEN}
- Parameter : productId 상품번호
- Body (JSON 형식) 
    {
        "productName": "닭가슴살 100g",
        "price": 1500
    }

• Header

  이름	내용	필수
  Authorization	Bearer{JWT_TOKEN}	O

• Body

  이름	타입	설명
  productName	String	추가 당시 상품의 이름
  price	Integer	추가 당시 상품의 가격

4. Response

- HTTP status : 201 Created
- Header : /products/${productid}
- Body 
    { 
      "message" : "성공"
    }

2. API Documentation tools

Swagger, Rest Docs, Postman, Notion, Etc..

3. API 설계를 먼저 하자

프론트엔드 개발자는 API 규격을 보고 작업을 한다.

API 명세가 나중에 나오면..

API 구현 기간 동안 API 호출 부분 작업을 못하거나,
임의로 API 주소, HTTP 메서드, 속성명을 사용하다가 모두 바꿔야 한다.

4. API 설계할 때 소통하자

API를 사용하는 사람 입장을 반영하자.

네이밍, 반환타입, JSON 구조,
로직 적용 책임 분배(정렬을 서버에서 or 프론트에서.. 등)

소통을 통해 함께 설계한다면, 서로의 리소스를 낭비하지 않을 수 있습니다.

5. 업데이트를 사전에 공유하자

업데이트는 반드시 사전 공유!!

API 스펙이 변경되면 클라이언트 코드도 변경되어야 하므로,

업데이트할 내용을 사전에 공유하고 조율하는 과정이 필수적입니다.

6. 상대방 입장에서 설명하자

나와 다른 관심사를 다루는 프론트엔드 개발자

상대방이 가장 궁금해 할 내용을, 상대방이 이해할 수 있도록
설명해야 합니다.