[BE 입문] 오픈소스 API 명세서 둘러보기

오늘은, BE 개발자로서 FE개발자 및 클라이언트와의 소통을 위해 가장 중요한 'API명세' 에 대해 숙지할 예정이다. API 명세를 직접 작성해보기 전에 감을 익히기 위해 인터넷에 공개되어 있는 공공데이터 API 문서 및 제공된 인터페이스 가이드들을 살펴볼 것이다.

가이드 문서는 주고받을 데이터의 룰 : (통신방법, 입력 파라미터, 출력 정보, 데이터 포맷) 등을 포함한다.

BE개발자는 필요한 데이터가 무엇일 지 고민해보고 해당 내용에 맞게 문서를 작성(요청 파라미터 생각, 응답 데이터 포맷 고려)한다.

---

총 3가지의 오픈 API 명세를 바탕으로, 각각 어떤 내용을 포함하고 있는지 살펴보았다.

1. 한국소비자원 - 생필품 가격 정보

[목적] 한국소비자원 참가격정보서비스에서 수집하는 상품별 생필품 가격 관련 데이터에 대한 상품정보 조회 API

• service URL

 http://openapi.price.go.kr/openApiImpl/ProductPriceInfoService/getProductInfoSvc.do
 http://(   여기가 서버주소   )/(이후 부터가 API 내 경로)

• Request parameter : Name(KOR), Name(ENG), size, require, sample, description
• Response Element : Name(KOR), Name(ENG), size, require, sample, description
• request sample code
• response message example
• (GET 방식은 보통 request Body가 필요하지 않음)

2. 쿠팡 OPEN APIs - 상품 승인 요청

외부 판매자들이 쿠팡 플랫폼에서 상품을 효율적으로 관리할 수 있도록 API를 제공 → 그중 “상품 승인 요청”

[목적] 판매자(클라이언트)의 임시저장 상태의 상품을 승인요청→승인완료 단계를 거쳐 “상품 페이지에 노출”하게 하기 위해서

• Path : HTTP method + URL path
• Example Endpoint : https 형식 주소 (https://(서버주소)/path)
• Request Parameter
  • Path Segment Parameter : Name, Requred, Type, Description (요청시 필요한 매개변수)
  • Request Example : not require body (PUT method지만, ID만으로 사용)
• Response Message
  • (Name, Type, Description) 여러 쌍
• Response Example
  • json 형식
• Error Spec
  • 에러 시, HTTP상태 코드 및 오류메세지와 해결 방법
• URL API Name

3. 빗썸 - 마켓 코드 조회

[목적] 빗썸에서 거래 가능한 마켓과 가상자산 정보를 제공

• 해당 API에 대한 설명
• Request 예시코드

  OkHttpClient client = new OkHttpClient();
  
  Request request = new Request.Builder()
    .url("https://api.bithumb.com/v1/market/all?isDetails=false")
    .get()
    .addHeader("accept", "application/json")
    .build();
  
  Response response = client.newCall(request).execute();

  요청 Path, HTTP method, Header 정보(데이터 형식)이 정의되어있음
  
• Response datas : (name, description, type)
• Query params (선택적. Defaults to false)
• Response state : 200, 400
• (GET 방식은 보통 request Body가 필요하지 않음)

4. LINE Pay - 기술 연동 가이드

[목적] LINE Pay 결제를 진행하기 전에 정상 가맹점인지 판단하고, 결제를 위한 정보를 예약

• 필요한 인증 정보 (channel id, channel secret key) → 헤더를 통해 전달
• HTTP 메서드
• content-type
• request header
• 요청 URL
• API 요청 파라미터 (파라미터 + request 바디 데이터)
  : Name, Type, Required, Description
• API 응답 데이터
  : Name, Type, Description
• API 요청 바디 예시
• API 응답 데이터 예시

---

모든 API 명세에 공통으로 포함되어있는, 반드시 필요한 정보는

• 요청 서비스 URL (Path)
• HTTP method
• Request 형식 (혹은 데이터 포맷)
• Response 형식 (혹은 데이터 포맷)

정도가 될 것 같다. 이 외에도 API 에 대한 간략한 설명, 통신 형식 (http 등), 필요시 query parameters, 그리고 response state 혹은 error state에 대한 설명도 있다면 아주 친절한 API명세서가 될 것 같다.

또한, 위 3가지 예시는 모두 not require request body 인 케이스이다. LINE Pay 기술 연동 가이드에만 GET이외의 바디가 필요한 메서드들이 포함되어있다. 일반적으로 GET method는 사용자(클라이언트)가 서버에게 데이터를 요청하는 작업이므로, 클라이언트쪽에서 서버쪽으로 데이터를 보낼 일이 없다. 따라서 GET메소드는 request body가 필요하지 않다. PUT, POST등에서는 일반적으로 request body가 필요하며, 이 경우 반드시 API명세에 표기해주어야 한다. 예외적으로 사용자 ID등 parameter만으로 PUT 을 하거나, 토큰만으로 사용하는 경우에는 PUT, POST일지라도 필요하지 않을 수 잇다.

request body가 필요한 경우에는 반드시 API 명세에 표기해야한다.
GET 메소드 등은 request body없이 parameter만으로 요청도 가능하다.

이제 이렇게 분석한 내용을 기반으로, 다음에는 내가 임의로 서비스를 가정하고 그 주제로 API 초안을 작성해보겠다.