Note 323 API, HTTP API, REST API

웹 스크레이핑을 하면 html 형식으로 데이터를 받고, 너무 많은 태그와 상속 관계 등이 존재해서 이 데이터를 보기 좋게 정제하는데 오랜 시간이 걸린다. Web API를 사용하면 보통 Json 형식으로 데이터를 리턴 받기 때문에 파이썬의 dictionary 형태로 데이터를 다룰 수 있게 된다. 항상 그런 것은 아니지만 API의 호출 제한이 있지 않다면 Web API가 웹 스크레이핑보다 더 쉬운 방법이 될 수 있다.

API는 사람마다, 기업마다 정의하는 방법이 다양해서, 이 모호한 정의 때문에 설명해주는 사람과 듣는 사람 모두가 헷갈린다. 이번 포스팅에서는 나의 언어로 API를 정의하고 여러가지 API들에 대해 정리해보자.

Interface

API를 알기 전, 인터페이스가 무엇인지 간략하게 알아보자. 위키피디아에 인터페이스를 검색하면, 서로 다른 시스템 간의 경계면이라고 나와있다. 이 말만 들으면 무엇을 의미하는지 전혀 와닿지가 않는다. 인터페이스는 추상화라는 단어를 통해 정의 될 수도 있는데 이 추상화라는 단어 자체가 모호하다. 개발자가 만든 코드가 정상적으로 작동할 때 우리는 이 프로그램이 개발/구현 되었다라고 한다. 개발자에게 추상화란, 개발자에게 직접 전달되기 전에 설계자 단계에서 만들어진 것을 의미한다. 또한, 개발이 완료된 후에 다른 사람에게 전달하기 위해 코드를 간략하게 요약한 것을 말한다. 이 두 단계 모두 실제 코드가 아닌 두루 뭉술한 단계를 이야기 하기 때문에 추상화라는 의미가 헷갈리고, 모호할 수 밖에 없다.

따라서, 나의 언어로 인터페이스를 정의하면 시스템 단계에서의 입력값과 출력값의 모음이 될 것 같다. 즉, 이 입출력의 모음은 프로그램이 실제로 구현이 되어 있지 않아도 어떤 입력을 하면, 어떤 출력이 나오는지의 알 수 있는 약속이 된다.

API(Application Programming Interface)

• API란? 인터페이스가 시스템 단계에서의 입,출력 모음이라면, API는 어플리케이션(프로그램) 단계에서의 입출력 모음이다. 프로그램이 구현되고 난 후 다른 사람에게 이 프로그램을 설명할 때 코드를 한줄한줄 알려주면서 이 프로그램이 어떻게 동작하는지 설명하는 사람은 거의 없을 것이다. 그 프로그램을 사용하는 사람이 원하는 것은 코드 한줄한줄이 아니라 입력을 넣으면 원하는 출력값이 나오는지에 대한 여부이다. 입력에 따른 정확한 출력을 위해서는 프로그램끼리 소통을 해야 하는데 어떻게 소통해야 하는가 약속된 것이 API이다.

• 예시

식당을 예로 들어서 고객, 웨이터, 메뉴판, 주방이 각각의 프로그램이 된다고 하자. 사용자는 입력을 하고 원하는 결과를 받고 싶어하는 Client, 주방은 Client가 원하는 결과를 만들어서 출력해주는 Server가 된다. 만약 메뉴판이 없다면 고객과 주방간에 정해진 약속이 없어서 입,출력이 제대로 이루어지지 않을 수 있다. 따라서 메뉴판이라는 정해진 약속, 즉 API가 존재하면 고객도 주문(입력)하기 편하고, 주방도 요리를 만들고 제공(출력)하기 편해진다. 그리고 만약 주방이 매우 바빠져서 더 효율적으로 식당을 운영하고 싶으면 웨이터를 이용할 수가 있다. 아까 주방을 Server라고 정의했는데, 여기서 웨이터는 사용자와 주방이 소통할 수 있도록 이어주는 중간다리 역할을 하기 때문에 웨이터를 API Server, 주방을 Server server라고 정의한다. 웨이터는 사용자에게 입력을 받고, 이 입력을 주방에 전달해줄 뿐만 아니라 주방의 출력을 사용자에게 전달해준다. 꼭 API Server가 있어야 하는 것은 아니지만, API Server가 존재하므로 Client와 Server server의 부담이 줄어들 수 있다.

• JSON(Javascript Object Notation)

Json은 이름 그대로 Javascript에서 Object를 표기하는 방법이다. 파이썬의 Dictionary와도 비슷한 구조이기 때문에 파이썬에서는 Dictionary처럼 사용을 해도 문제가 없다. API의 응답은 다양하지만 보통 Json형태로 많이 이루어진다.

HTTP(HyperText Transfer Protocol)

HTTP는 컴퓨터들의 통신 규약 중 하나이다. 여기서 프로토콜은 하나의 컴퓨터가 다른 컴퓨터와 소통할 때(파일 주고 받고) 정해진 규칙과 틀이다. 이 규칙과 틀을 지키지 않아도 소통이 가능할테지만, 사람마다 기업마다 이 규칙이 다르다면 너무나 다양한 소통방법이 존재해서 정보를 공유할 때 매우 불편할 것이다. 따라서 HTTP에서는 HTTP Method라는 것을 사용해 이 규칙을 지키도록 권고함으로써 네트워크 간 통신이 원활하게 하고, 다른 컴퓨터 혹은 사람과의 공유도 수월하게 한다.

• HTTP Request, Response

HTTP는 크게 요청(Request)와 응답(Response)으로 나누어져있다. 요청은 보통 한 컴퓨터가 다른 컴퓨터에 리소스 요청을 보낼 때 사용된다. 다른 컴퓨터에 있는 자원을 사용해도 되겠냐는 요청이다. 보통 요청을 하는 컴퓨터를 클라이언트, 받는 컴퓨터를 서버라고 한다.

클라이언트가 요청을 보내면 서버는 응답을 해야한다. HTTP 규약을 통해서 요청을 보냈기 때문에 응답도 HTTP 규약에 따르게 된다. 각 응답에는 기본적으로 상태 코드(Status Code)라는 것이 있는데 상태 코드는 크게 5개의 종류로 나눈다.

1) 100 번대 : 정보 응답

2) 200 번대 : 성공 응답

3) 300 번대 : 리다이렉션 메시지

4) 400 번대 : 클라이언트 에러 응답

5) 500 번대 : 서버 에러 응답

• CRUD에 사용되는 HTTP 메소드

1) GET: 특정 리소스를 달라고 할 때(ex. 페이지 로딩)

2) POST: 클라이언트가 서버에 많은 정보를 전달할 때(ex. 회원가입시 유저의 정보 저장. 보통 JSON처럼 한 줄로 표현되기 힘든 데이터를 전달할 때.)

3) PUT/PATCH: 서버의 특정 리소스를 업데이트 할 때. PUT은 전부, PATCH는 일부를 바꿀 때 사용(ex. 사용자 닉네임 변경)

4) DELETE: 서버의 특정 리소스를 삭제할 때(ex. 유저탈퇴)

이 메소드들이 여기 보여지는 기능만 하는 것은 아니다. GET을 통해서도 서버에 정보를 전달 할 수 있다. 다른 메소드들도 여러가지 기능을 수행할 수 있다. 하지만, 메소드들의 기능을 규칙없이 다양하게 사용하면 작동에는 문제가 없어도 다른 사람과 공유할 때 문제가 생길 것이다. 또한, 다음과 같은 HTTP 메소드 외에도 다양한 메소드들이 존재한다.이 자세한 메소드들은 MDN 문서를 참고해보자.

REST API

위에서 HTTP Method는 개발자들끼리 정한 규칙이고, 권고사항이라고 했다. 하지만, 이 권고사항들이 잘 지켜지지 않기 때문에 이 중에서 중요한 규칙을 뽑아서 HTTP API(Web API)가 지켜야 할 6개의 가이드라인을 만들었고, 이 가이드라인을 REST API라고 한다. 이 REST API 역시 권고사항이기 때문에 모든 Web API가 이 REST API를 지키는 것은 아니다. 그래서 지키지 않은 API와는 다르게 이 6개의 가이드라인을 다 따르는 API를 RESTful API라고 한다. RESTful API는 보통 웹 주소만 보고도 그 웹이 어떤 정보를 표현하고 있는지 어느정도 파악이 가능하다. 카카오, 구글에서 제공하는 API는 REST API를 따르려고 노력한다고 한다.

가이드라인은 https://restfulapi.net/rest-api-design-tutorial-with-example/ 을 참고하자.

보통 REST API를 작성했다고 하면 HTTP Request의 메소드는 다음과 같이 사용한다. 반드시 이렇게 사용해야 하는 것은 아니다.

• GET(READ): 데이터 조회(가져옴)

• POST(CREATE): 데이터 생성

• PATCH(UPDATE): 데이터 일부 업데이트

• PUT(UPDATE): 데이터 전체 업데이트

• DELETE(DELETE): 데이터 삭제

REST API를 따르는 HTTP Response에서 사용되는 상태 코드를 몇 가지 본다면

• 200 (OK)

• 201 (Created)

• 202 (Accepted)

• 204 (No Content)

• 301 (Moved Permanently)

자세한 상태 코드는 https://restfulapi.net/http-status-codes/ 참고하자.

Open Weather API 활용

아래의 사이트의 API를 활용하여 날씨 데이터를 불러올 수 있다.

https://home.openweathermap.org/

API_KEY = '...'
city_name = 'Seoul'
url = f'https://api.openweathermap.org/data/2.5/weather?q={city_name}&appid={API_KEY}'
req = requests.get(url)
current_weather = json.loads(req.text)
print(current_weather['weather'][0]['description']) # 현재 날씨에 대한 설명
print(current_weather['main']['temp_min']) # 날씨 최저온도. 절대 온도이기 때문에 -273해서 섭씨로 변환 할 수 있음.

twitter API 활용

미리 받아놓은 Key를 활용하여 트위터 댓글의 정보를 가져올 수 있다.

import tweepy

def connect_api():
    """
    connect_api 함수는 tweepy 로 API 를 연결한 'api' 객체를 리턴합니다.

    Hint: api 객체는 tweepy.API 로 만들 수 있습니다.
    """

    api_key = '...
    api_key_secret = '...
    access_token = '...
    access_token_secret = '...
    
    auth = tweepy.OAuthHandler(api_key, api_key_secret)
    auth.set_access_token(access_token, access_token_secret)

    api = tweepy.API(auth)

    return api

api = connect_api()
#tweet_mode를 compat으로 하면 140자 이후부터는 글자가 잘린다.
#extended로 해주어야 140자 이상의 글자도 잘리지 않고 표현 가능하다.
tweets = api.user_timeline('bts_official', tweet_mode = 'extended') # tweet_mode는 3.10.0 버전에서 사용가능. 최신버전은 안 되는듯
for t in tweets:
  t.full_text # bts 공식 계정에 있는 댓글들을 볼 수 있음.