[프로젝트] API 명세 작성하기 - 1

냅다 따라하는 클론 코딩에서는 API 명세가 필요 없었지만, 많은 기능을 담은 웹페이지를 구현하다 보니 어떤 API에서 어떤 파라미터를 사용하고, 프론트와 백에서의 변수 정리가 필수겠다는 판단이 들었다.

이에 이번 포스팅에서는 API 명세를 작성하기 위한 배경지식을 간단히 정리하고, 이를 기반으로 다음 포스팅에서 API 명세를 작성해보고자 한다.

 

용어와 개념

API란?

Application Programming Interface, 응용프로그램 프로그래밍 인터페이스

API의 개념을 설명할 때에는 종종 레스토랑의 점원으로 비유되고는 한다. 즉, API는 손님(프로그램)이 주문할 수 있도록 메뉴(명령 목록)을 정리해주고, 주문(명령)을 받으면 요리사(응용프로그램)와 상호작용하여 요청된 메뉴(명령에 대한 값)을 전달한다는 것이다.

출처 : wishket blog (www.blog.wishket.com)

쉽게 말해, API는 프로그램들이 서로 상호작용하는 것을 도와주는 중간 매개체라고 볼 수 있다. 즉, 인간이 아닌 코드들끼리 소통하기 위해 만들어진 것이다.

API는 서버에서 만들며, 응용프로그램에서 어떤 메뉴를 요청하면 어떤 기능을 수행할지를 정하는 것이라 볼 수 있다. 따라서 서버 단에서 API와 API 명세서를 작성함으로써 클라이언트 단에서 그 API를 활용하여 클라이언트 화면을 구성하고 개발할 수 있게 된다.

 

API의 역할

• 서버와 데이터베이스에 대한 출입구(접근 권한 부여) 역할을 한다. (허용된 사람에게만 접근성 부여)
• 응용프로그램과 기기가 원활히 통신할 수 있도록 한다. 
• 모든 접속을 표준화한다. (기계, 운영체제 등과 상관 없이 누구나 동일한 액세스를 얻을 수 있다.)

 

📍

API를 통해 개발자들이 응용프로그램 코드 작성 방법을 표준화할 수 있어 간소화되고 빠른 프로세스 처리가 가능해진다. 또, 개발자들의 협업도 용이해진다.

 

 

 

REST API란?

REpresentational State Transfer API, 자원의 이름을 기반으로 하여 상태를 주고 받는 것

REST API에서는 JSON¹이나 XML² 형태로 데이터를 주고 받는 것이 일반적이며, URI³를 통해 자원을 명시하고 HTTP 프로토콜⁴에서 제공하는 메소드를 활용하여 해당 자원에 대한 CRUD⁵를 동작하게 하는 API이다. 

 

▼ 위의 문장을 이해하기 위한 용어 정리 📚

JSON

JavaSript Object Notation

JavaScript에서 객체를 만들 때 사용하는 표현식을 의미한다. 데이터를 저장하거나 전송할 때 많이 사용되는 경량의 DATA 교환 형식이다.

• JSON 표현식은 사람과 기계 모두 이해하기 쉽다.
• 용량이 작아 최근에는 XML을 대체하여 데이터 전송에 많이 사용한다.
• JSON = 데이터 포맷일 뿐 - 어떠한 통신 방법도, 프로그래밍 문법도 아닌 단순히 데이터를 표시하는 표현방법이다.
• 표현 방법 : 태그(Tag)로 표현하지 않고, 중괄호({}) 형식과 함께 값을 ,로 나열하여 표현이 간단하다.

{
  "employees": [
    {
      "name": "Surim",
      "lastName": "Son"
    },
    {
      "name": "Someone",
      "lastName": "Huh"
    },
    {
      "name": "Someone else",
      "lastName": "Kim"
    } 
  ]
}

 

 

XML

eXtensible Markup Language, 확장 가능한 마크업 언어

HTML과 매우 비슷한 문자 기반의 마크업 언어(test-based markup language)이다. 그러나 XML은 HTML처럼 데이터를 보여주는 것이 목적이 아니고, 데이터를 저장하고 전달할 목적으로만 만들어졌다. 또한, XML 태그는 HTML 태그처럼 미리 정의되어 있지 않고, 사용자가 직접 정의할 수 있다.

XML의 특징

• Extensible(=확장 가능한) : 데이터를 설명하는 태그(Tag)를 사용자 마음대로 정의할 수 있어 확장성이 있다.
• HTML과 달리 Tag가 미리 정의되어 있지 않다.
• JSON 역시 데이터 포맷일 뿐 - 어떠한 통신 방법도, 프로그래밍 문법도 아닌 단순히 데이터를 표시하는 표현방법이다.
• 표현방법 : 데이터값 양쪽으로 Tag가 있다. (HTML을 근본으로 했기 때문!)

<?xml version="1.0" encoding="euc-kr" ?>
<북산고등학교선수목록>
     <선수명단>
          <이름>채치수</이름>
          <학년>3</학년>
          <등번호>4</등번호>
          <포지션>C</포지션>
          <키>197</키>
          <체중>93</체중>
     </선수명단>
     <선수명단>
          <이름>권준호</이름>
          <학년>3</학년>
          <등번호>5</등번호>
          <포지션>F</포지션>
          <키>178</키>
          <체중>62</체중>
     </선수명단>
     <선수명단>
          <이름>정대만</이름>
          <학년>3</학년>
          <등번호>14</등번호>
          <포지션>SG</포지션>
          <키>184</키>
          <체중>70</체중>
     </선수명단>
     <선수명단>
          <이름>송태섭</이름>
          <학년>2</학년>
          <등번호>7</등번호>
          <포지션>PG</포지션>
          <키>168</키>
          <체중>59</체중>
     </선수명단>
     <선수명단>
          <이름>강백호</이름>
          <학년>1</학년>
          <등번호>10</등번호>
          <포지션>PF</포지션>
          <키>189.2</키>
          <체중>83</체중>
     </선수명단>
     <선수명단>
          <이름>서태웅</이름>
          <학년>1</학년>
          <등번호>11</등번호>
          <포지션>SF</포지션>
          <키>187</키>
          <체중>75</체중>
     </선수명단>
</북산고등학교선수목록>

 

AJAX

Asynchronous JavaScript and XML

JavaScript를 통해 비동기식으로 XML을 이용하여 서버와 통신하는 방식으로, 빠르게 동작하는 동적인 웹페이지를 만들기 위한 개발 기법의 하나이다.

Ajax는 웹페이지 전체를 다시 로딩하지 않고도, 웹 페이지의 일부분만을 갱신할 수 있게 해준다. 즉, Ajax를 이용하면 백그라운드 영역에서 서버와 통신하며 그 결과를 웹페이지의 일부분에만 표시할 수 있다는 것이다.

이 때 서버와는 JSON, XML, HTML, 텍스트 파일과 같은 다양한 형태의 데이터를 주고받을 수 있다.

AJAX의 동작 방식

1. Request (요청) : JavaScript가 (XMLHttpRequest 객체를 통해) 서버에 정보를 요청한다.  → 서버는 응답으로 데이터(XML, JSON)를 XMLHttpRequest객체에 전송한다.
2. Response (응답) : JavaScript는 콘텐츠를 처리하여 페이지에 추가한다.

 

URI

Uniform Resource Identifier, 통합 자원 식별자

인터넷에 있는 자원을 나타내는 주소이다. 따라서 URI라는 개념은 어떤 형식이 있다기 보다는 특정 자원을 식별하는 문자열을 의미한다.

URL과 URN의 상위 개념으로, 자원을 위치로 식별하면 URL, 고유한 이름으로 식별하면 URN이다.

URI의 구조

URI 설계 원칙

1. /(슬래시)는 계층 관계(is a)를 나타낼 때 사용한다. (animal 안에 human이 포함돼있다. human is animal.)

https://www.ojjambbong.com/animal/human

2. ?(쿼리 스트링)은 속성(has a)를 나타낼 때 사용한다. (human은 gender라는 속성을 갖고 있다. human has a gender type.)

https://www.ojjambbong.com/animal/human?gender=female

3. URI의 마지막에는 /(슬래시)를 붙이지 않는다.

https://www.ojjambbong.com/animal/human/ (x)
https://www.ojjambbong.com/animal/human  (o)

4. URI의 가독성을 위해 _(언더바)는 사용하지 않고 -(하이픈)을 사용한다.

https://www.ojjambbong.com/animal/human?gender_type=female (x)
https://www.ojjambbong.com/animal/human?gender-type=female (o)

5. 소문자 사용이 권장되고 파일 확장자를 포함하지 않는다.

https://www.ojjambbong.com/animal/HUMAN?gender_type=female (x)
https://www.ojjambbong.com/animal/human?image.jpeg         (x)

 

URL

Uniform Resource Locator, 통합 자원 지시자

 URL은 URI의 가장 흔한 형태이며, 특정 서버의 한 리소스에 대한 구체적인 위치를 서술한다.

URL은 리소스가 정확히 어디에 있으며, 어떻게 접근할 수 있는지를 분명히 알려준다.

• http://naver.com - 네이버 사이트의 URL
• http://img.naver.net/static/www/dl_qr_naver.png- 네이버 앱 QR 코드의 이미지에 대한 URL
• http://news.naver.com/main/main.nhn?mode=LSD&mid=shm&sid1=104 - 네이버 뉴스에서 분류 중 "세계" 주제의 기사에 대한 URL 

 

URN

Uniform Resource Name, 통합 자원 이름

 URL은 URI의 또 다른 형태이며, 콘텐츠를 이루는 한 리소스에 대해 그 리소스의 위치에 영향받지 않는 유일무이한 이름 역할을 한다. 따라서 이 위치 독립적인 URN은 리소스를 여기저기로 옮기더라도 문제 없이 작동한다.

예를 들어, 다음의 URN은 인터넷 표준 문서 'RFC 2141'이 어디에 있든 상관 없이 이 리소스를 지칭하기 위하여 사용될 수 있다는 것이다.

• urn:ietf:rfc:2141 - 'RFC 2141' 문서

단, URN은 아직 실험 중인 상태로 널리 채택되지 않아 접하기 쉽지 않다.

 

CRUD

Create, Read, Update, Delete

CRUD는 대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인 Create(생성), Read(읽기), Update(갱신), Delete(삭제)를 묶어서 일컫는 말이다.

API에서 CRUD는 클라이언트가 서버에게 보내는 요청들을 크게 4가지 성격으로 분류한 요청들이다. 

Create = POST

서버에 정보를 올려달라는 Create는 POST 메서드를 사용하여 요청한다. POST를 통해 해당 URI를 요청하면 리소스를 생성한다.

Read = GET

서버에서 정보를 불러오는 Read는 GET 메서드를 사용하여 요청한다. GET을 통해 해당 리소스를 조회하고, 해당 도큐먼트에 대한 자세한 정보를 가져온다.

Update = PUT, PATCH

정보를 바꾸는 Update는 PUT 또는 PATCH 메서드를 사용하여 요청한다. PUT은 데이터 전체를 바꾸고 싶을 때, PATCH는 데이터의 일부만 수정하고 싶을 때 사용한다.

Delete = DELETE

정보를 지우는 Delete는 DELETE 메서드를 사용하여 요청한다. DELETE를 통해 리소스를 삭제할 수 있다.

 

HTTP

HyperText Transfer Protocol

웹 환경에서 정보를 주고 받기 위한 프로토콜(통신 규약, 약속)이다.

TCP/IP는 클라이언트/서버 모델을 사용하는 프로토콜이며, 클라이언트의 요구에 대응하여 서버가 페이지 및 데이터를 보낸다. HTTP는 이러한 TCP/IP 프로토콜을 기반으로 한 프로토콜로, 클라이언트와 서버 간에 HTTP 요청과 HTTP 응답을 할 수 있다.

HTTP는 이전 상태를 저장하지 않는 특성을 지니는데, 각각의 요청/응답은 독립적인 것으로 전에 보낸 요청 및 응답을 알지 못한다는 의미이다. 따라서 이러한 진행 과정이나 그에 대한 데이터가 필요할 때에는 쿠키나 세션을 활용한다.

HTTP의 구조

HTTP 요청(Request)과 응답(Response)은 모두 headers과 body라는 공통된 구조를 가지고 있으며, 이에 더해 각각 Request는 start line, Response는 status line이라는 구조가 있다.

 

HTTP 상태코드

클라이언트는 서버가 보내는 HTTP의 상태코드를 확인하여 요청의 성공/실패 여부를 확인할 수 있다.

상태 코드는 3자리 숫자로 만들어져 있으며, 첫번째 자리는 1에서 5까지 제공된다. (첫번째 자리가 4와 5인 경우는 정상적인 상황이 아니기 때문에 사이트 관리자가 즉시 알아야 하는 정보이다.)

• 1xx(정보) : 요청을 받았으며 프로세스를 계속 진행합니다.
• 2xx(성공) : 요청을 성공적으로 받았으며 인식했고 수용하였습니다.
• 3xx(리다이렉션) : 요청 완료를 위해 추가 작업 조치가 필요합니다.
• 4xx(클라이언트 오류) : 요청의 문법이 잘못되었거나 요청을 처리할 수 없습니다.
• 5xx(서버 오류) : 서버가 명백히 유효한 요청에 대한 충족을 실패했습니다.

 

 

이러한 간단한 개념을 바탕으로, API 명세를 작성해보는 내용은 다음 포스팅에서 마저 알아보도록 한다. 

 

 

---

참고 사이트

• wishket 블로그 (https://blog.wishket.com/api%EB%9E%80-%EC%89%BD%EA%B2%8C-%EC%84%A4%EB%AA%85-%EA%B7%B8%EB%A6%B0%ED%81%B4%EB%9D%BC%EC%9D%B4%EC%96%B8%ED%8A%B8/)
• keepcalm님 블로그 (https://velog.io/@keepcalm/API-%EA%B8%B0%EB%B3%B8-%EA%B0%9C%EB%85%90-%ED%8C%A8%ED%82%B7-%ED%97%A4%EB%8D%94-%EB%B0%94%EB%94%94-CRUD-URI-path-variable-%EB%AA%85%EC%84%B8%EC%84%9C)
• TCP School (www.tcpschool.com)
• 재우님 블로그 (https://m.blog.naver.com/PostView.naverisHttpsRedirect=true&blogId=chaeng1010&logNo=30041799169)
• 마이구미의 HelloWorld:티스토리 (https://mygumi.tistory.com/139)
• pock11님의 블로그 (https://velog.io/@pock11/REST-API-CRUD)
• jaeseongdev님의 블로그 (https://jaeseongdev.github.io/development/2021/04/22/REST_API%EC%97%90%EC%84%9C%EC%9D%98_HTTP_%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C_%EC%83%81%ED%83%9C%EB%A9%94%EC%8B%9C%EC%A7%80.md/)
• https://www.whatap.io/ko/blog/40/