API의 개요

API의 개념

API(Application Programming Interface)는 응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어하기 위한 인터페이스이다. (인터페이스 : 여러 장치나 프로그램 사이에서 통신이 가능하도록 도와주는 매개체)

API 개발 순서

클라이언트와 서버 간의 통신을 담당하는 인터페이스인 API를 개발하는 순서는 다음과 같다.

엔드포인트 설계 : 요청을 보낼 서버의 주소를 설정하고(예 : https://wwww.gilbut.co.kr), 해당 경로에 대해 어떤 API를 요청할지 최종 엔드포인트(/search, /curation)를 정의한다. 그러면 다음과 같은 하나의 경로에 여러 엔드포인트를 정의할 수 있다.
- https://wwww.gilbut.co.kr/search
- https://wwww.gilbut.co.kr/curation
HTTP 메서드 지정 : 각 엔드포인트에 요청할 HTTP 메서드를 지정한다.
데이터 포맷 및 프로토콜 선택 : API에서 사용할 데이터 포맷, 즉 주고 받을 데이터의 형탱롸 통신에 사용할 프로토콜을 선택한다. 일반적으로 데이터 포멧은 JSON, 프로토콜은 RESTful을 많이 사용한다.(RESTful은 하단에 자세히 설명함)
엔드포인트 구현 : 각 엔드포인트로 접수된 클라이언트의 요청을 처리하는 서버 측 로직을 구현한다. 클라이언트의 요청을 받으면 데이터베이스에 접근해 데이터를 가져와 가공하고, 이를 클라이언트에 반환하는 프로그램 로직을 만든다.
인증 및 보안 : API를 보호하기 위해 인증 및 보안 메커니즘을 구현한다. 사용자 인증, 액세스 토큰 기반의 권한 부여, 암호화 등의 보안 기능 등이 이에 포함된다.
오류 및 예외 처리 : 잘못된 요청이나 예외 상황에 대해 적절한 오류 응답을 할 수 있또록 프로그램 로직을 보강한다. 이를 통해 클라이언트가 오류를 인식하고 적절히 처리할 수 있게 한다.
테스트와 디버깅 : API 개발 작업은 테스트와 디버깅 단계를 거쳐야 한다. 그럼으로써 API의 정확성과 안정성을 확인하고, 문제를 해결하며, 성능을 최적화 할 수 있다.
API 문서화 : API를 사용하는 다른 개발자가 쉽게 이해하고 사용할 수 있도록 문서화하는 단계이다. API의 엔드포인트, 매개변수, 응답 형식, 오류 코드 등에 대한 명세를 문서로 작성함으로써 개발자가 API를 좀 더 효과적으로 활용할 수 있다.

API의 유형

API의 유형에는 대표적으로 REST API와 GraphQL이 있다.

REST API

API의 형식이 너무 자유로우면 개발자끼리 API를 이해하고 사용하는 데 오랜 시간이 걸린다. 따라서 이를 해결하기 위해 API 작성 규칙을 표준화한 REST API(REpresentational State Transfer API)가 개발됐다.

REST API의 구성 요소

REST API는 크게 자원(resource), 행위(verb), 표현(representation of resource)으로 구성 된다.

자원 : REST API는 클라이언트와 서버가 주고 받는 자원(텍스트, 이미지, 음악, 영상 등)을 URI로 명시한다. URI는 URL보다 상위 개념으로, 특정 자원 자체를 의마한다. 한편 URL은 웹상에서 자원이 있는 곳의 위치를 뜻한다.
- 예를 들어 길벗 사이트의 사용자 페이지 URL이 https://www.gilbut.co.kr/users 라면 100번째 사용자를 가리키는 URL은 https://www.gilbut.co.kr/users/100 이 될 수 있다.
URI의 구조는 다음과 같다. scheme:[//[user[:password]@]host[:port]][/path][?query][#fragment]
- scheme : 사용할 프로토콜의 종류(http, https 등)을 나타낸다.
- user와 password : 서버에 저장된 데이터에 접근하는 데 필요한 사용자의 이름과 비밀번호로, 없는 경우 생략할 수 있다.
- host와 port: 접긍ㄴ할 서버의 호스트명(도메인, IP 주소 등)과 포트 번호이다
- path : 접근할 서버의 경로에 대한 상세 정보이다.
- query : 접근할 대상에 전달하는 추가 정보이다.
- fragment : 메인 자원 내에 있는 서브 자원에 접근할
- 때 이를 식별하기 위한 정보이다.
행위 : HTTP 메서드를 통해 자원에 CRUD 연산을 적용하는 것을 의미한다.
표현 : 클라이언트가 서버에 자원을 요청하면 서버는 요청받은 시점의 자원 상태를 반환한다. 자원 상태는 CRUD 연산에 의해 매번 바뀐다. REST API는 이렇게 변하는 자원 상태를 반영해 요청 받은 시점의 자원 상태를 반환한다. 이때 주고받는 자원, 즉 데이터의 형식은 JSON 또는 XML이다.

REST API의 특징

REST API의 가장 큰 특징은 HTTP 요청 메시지만 보고도 어떤 동작이나 정보를 요청하는지 쉽게 할 수 있다는 것이다.

POST /users HTTP/1.1 --- 시작 행
(중략) --- 헤더
      ---빈행
{
  "name" : "inderby"  --- 본문
}

위의 메시지 처럼 POST를 통해 새로운 사용자를 생성하라는 요청임을 쉽게 알 수 있다.

REST API 설계 규칙

REST API를 설계할 때의 핵심은 구성 요소, 즉 자원, 행위, 표현을 역할에 맞게 잘 활용하는 것이다.

URI에 명사를 사용한다. : 가장 중요한 규칙이다. /getUserById 와 같이 URI에 명사가 아닌 동사가 포함되면 API의 의미를 쉽게 추론할 수 없다.
자원의 계층 관계를 /로 나타낸다. : 이러한 관계를 ‘has-a’관계라고 한다.
마지막에 /를 넣지 않는다.
명사와 명사를 구분할 때 -을 사용한다.
소문자만 사용한다.
파일 확장자를 포함하지 않는다.
적절한 HTTP 상태 코드를 응답한다.

GraphQL

GraphQL(Graph Query Language)은 페이스북에서 만든 쿼리 언어로, 클라이언트가 서버로부터 데이터를 효율적으로 가져오기 위해 개발 됨. REST API는 중식당처럼 백엔드 개발자가 미리 만들어놓은 API만 요청할 수 있다. 따라서 응답 받는 데이터의 조합이 정해져 있다. 반면 GraphQL은 원하는 데이터를 직접 조합하여 요청할 수 있다.

즉, ‘URI + HTTP 메서드’ 조합으로 다양한 엔드포인트가 존재하는 REST API와 달리 GraphQL은 URI 하나로 필요한 데이터를 조합한 쿼리를 요청한다.(그렇다고 GraphQL이 우월한 것은 아니다)

엔드포인트가 여러 개인 REST API는 메뉴가 여러 개인 중식당과 같고, 엔드포인트가 히나 뿐인 GraphQL은 메뉴가 하나인 마라탕 식당과 같다(?)

API 명세서

클라이언트와 서버가 API를 이용해 통신하려면 어떤식으로 요청을 보내고 무엇을 응답 데이터로 받을지 약속해야 한다. API 명세서(API specification)는 이러한 약속을 정리한 문건으로, API를 정확하게 호출하고 그 결과를 명확히 해석하는데 필요한 정보가 일관된 형식으로 기술돼 있다.

API 명세서 작성 방법

API 명세서는 API 목차 시트를 만든 후 API 별로 세부 명세를 기술하는 순서로 작성한다. API 명세서는 마이크로소프트 워드, 엑셀, 노션 등으로 만들 수 있다.

API 목차 시트 만들기

API 목차 시트는 수 많은 API를 표 형태로 만들어 한눈에 볼 수 있도록 정리한 것이다. 목차 시트가 있어야 필요한 API를 빠르게 찾아 세부 명세 시트로 이동할 수 있다. 목차 시트는 크게 URL 부분과 API 목차 부분으로 나눠 작성한다. 목차 부분에는 각 API의 메서드, 하위 URI, API에 대한 설명, 명세서 작성 여부, 서버 반영 여부 등의 정보가 담겨 있다.

API뱔 세부 명세 작성하기

API 목차 시트를 만들었다면 API별로 세부 명세를 별도 시트에 작성한다. 세부 명세에는 해당 API 요청과 응답을 정확히 주고 받는데 필요한 내용이 들어간다. 필요한 내용들 : Method, Header, Body, Query String, Path Variable, Response Parameters, Response Sample, Result Code

오픈API: 스웨거

오픈API(OAS, OpenAPI Specification)는 REST API를 문서화하기 위한 공개 표전(open standard)으로, REST API 명세서를 작성하는 포맷을 제공한다. 대표적으로 Swagger가 있다. 다음과 같은 특징이 있다.

자동으로 API 명세서를 생성하고 스웨거 UI를 통해 API 명세서를 시각적으로 구조화해 보여준다.
프론트엔드 개발자가 실시간으로 업데이트된 API 문서를 확인하고 각 API의 기능, API 요청 시 전달되는 매개변수, 응답 데이터의 형식 등을 쉽게 이해할 수 있다.
API 명세서를 토대로 API 테스트(API 요청을 보내고 응답을 확인할 수 있다. 클라이언트 개발자가 API를 직접 테스트하고 디버깅할 수 있어 개발 시간이 단축된다.) 하지만 학습하는 데에 진입 장벽이 좀 있다.

part4. API