API_정의, 명세

API  application programming interface

뭐.. 손님의 요구를 요리사에게 전달하는 점원.. 이라는데 1도 모르겠음 좀더 현실적으로 정리된 글이 필요하다.

 

클라이언트에서 서버쪽에 필요한 데이터(정보)를 요청한다. 그럼 서버에 어떻게 접근해서 어떻게 데이터를 제공할것인가?

 

이 질문에서 시작하면 편하다.

• 이 클라이언트는 서버와 데이터베이스에 접근해도 되는가? (보안)
• 정보 요청의 폼(템플릿)은 어떻게 되는가? (원하는 데이터 종류, 타입등등)

이런 것들을 정해주는게 API이다.

클라이언트와 서버 사이에서 request, response 규칙, 정보를 원활하게 주고받기 위해 정리한 메뉴얼

 

API 명세

API가 클라이언트와 서버가 데이터를 원활하게 주고받기 위한 인터페이스라면,

API 명세서는 API를 사용하기 위한 약속을 정리한 문서이다.

 

즉, BE는 API 명세서가 있어야 기능을 정의하고 작업 할 수 있고, FE는 API 명세서를 바탕으로 백엔드에서 어떤 값이 필요하고 전달해줄 지 알고 작업할 수 있다.

 

이번 위클리톤같은 경우, API 명세가 늦어졌고, 이로 인해서 

• 내가 작성한 API조차 프론트에서 원하는 값을 제공하는지, 내가 원하는 request를 받는지 헷갈렸다.(개발하면서 API를 계속 수정할 위험↑)
• API가 아닌 동적으로 들어오는 값에 맞춰서 작업하게 됨 (협업의 의미가 없고 API를 미리 작성한 의미도 없다.)

이런 위험 가능성이 있었다.

 

때문에 API 명세서는 상당히 중요하다.

 

명세서에는 

기능   메소드   API 입력데이터(Request)   반환데이터(Response)   에러

가 필요하다.

 

기능

이 API가 무엇을 하는 API인지

→ 사용자의 여행타입 등록

 

메소드

데이터를 대상으로 하는 행위 그 자체.

• GET : 리소스 조회
• POST : 요청 데이터 처리(등록)
• PUT : 리소스를 대체, 없으면 생성 (업데이트)
• PATCH : 리소스 부분 변경 (수정)
• DELETE : 리소스 삭제

→ 설문 정보를 기반으로 사용자의 여행타입을 "등록"하는 것이므로 POST

 

API 입력데이터(Request)

HTTP 메세지 바디에는 서버로 전송할 데이터가 담긴다.

HTTP API 전송 기준으로 데이터 타입은 다양하게 있지만 (Json, XML, yaml, csv등) 주로 Json을 사용한다.

 

Json 객체는 {} 로 묶여서 key : value 로 구분한다.

→ (question1같은 변수명은 예시)

{
  "question1": true,
  "question2": true,
  "question3": false,
  "question4": false,
  "question5": true,
  "question6": true,
  "question7": true
}

 

반환데이터(Response) 

클라이언트로부터 요청받은 내용과 데이터를 서버가 처리한 결과를 반환한다.

(수정된 자원, 새로 추가된 정보, 처리에 대한 설명 등)

→ 마찬가지로 json 형태로 반환

{
  "travelType": "씩씩한 다람쥐"
}

 

에러

에러는 HTTP 상태코드로 나타낼 수 있다.

상태코드 : 클라이언트가 보낸 요청의 처리 상태를 응답에서 알려주는 코드

 

문제가 생겼을 때 HTTP 상태코드는 400번대와 500번대이다.

(하지만, 500번대는 서버자체의 오류로, 서버가 터지거나, 화재가 나는 등 서버자체에 문제가 생긴게 아니라면 500은 사용하면 안된다. 500번대 상태코드는 서비스 자체에 심각한 문제가 생겼다는 뜻.)

 

주로 나타나는 400번대 코드

400	BAD_REQUEST	필수 파라미터 없음
401	UNAUTHORIZED	계정 인증 실패 (인증 정보 오류)
402	DUPLICATED_KEY	중복된 키 오류
403	FORBIDDEN	계정 인증 실패 (잘못된 계정)
404	NOT FOUND	요청 리소스를 찾을 수 없음
405	PERMISSION_DENIED	권한 부족
406	BAD_PARAMETER_RECEIVED	잘못된 파라미터 정보