REST API, OpenAPI, API Key

REST API 소개

REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었습니다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 합니다.

REST API는 HTTP를 사용하여 시스템 간 통신을 허용하며, Representational State Transfer (REST)의 원칙에 기반합니다.

REST API는 Representational State Transfer API의 약자입니다. HTTP 요청을 사용하여 웹 서비스와 상호 작용하는 타입의 API입니다. REST API는 웹의 기존 인프라를 사용하여 데이터를 전송하고 처리하는 것이 가능합니다. HTTP의 기본 요청 메소드(GET, POST, PUT, DELETE)를 사용하여 REST API를 구축할 수 있습니다. REST API의 원칙은 Representational State Transfer (REST)에 기반합니다.

REST API는 웹 기반 API를 만드는 것을 위한 인기있는 방법입니다. 웹 서비스가 어떻게 생성되고 접근되어야 하는지 정의하는 아키텍처 스타일입니다. 이 블로그 게시물에서는 REST API가 무엇인지, 왜 중요한지, 어떻게 작동하는지 살펴보겠습니다.

---

REST API의 중요성

REST API의 중요성은 웹 상에서 데이터와 애플리케이션을 교환하는 것이 쉽다는 것에서 비롯됩니다. REST API를 사용하면 웹 애플리케이션, 모바일 애플리케이션, 데스크탑 애플리케이션 등 다양한 플랫폼과 연동할 수 있습니다. 이는 데이터의 통신 및 공유를 단순화하고 시스템 간의 통신을 용이하게 만듭니다.

---

REST API 중심 규칙

1) URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)

    GET /members/delete/1

위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원을 표현하는데 중점을 두어야 합니다. delete와 같은 행위에 대한 표현이 들어가서는 안됩니다.

2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현

위의 잘못 된 URI를 HTTP Method를 통해 수정해 보면

    DELETE /members/1

으로 수정할 수 있겠습니다.
회원정보를 가져올 때는 GET, 회원 추가 시의 행위를 표현하고자 할 때는 POST METHOD를 사용하여 표현합니다.

회원정보를 가져오는 URI

    GET /members/show/1     (x)
    GET /members/1          (o)

회원을 추가할 때

    GET /members/insert/2 (x)  - GET 메서드는 리소스 생성에 맞지 않습니다.
    POST /members/2       (o)

[참고]HTTP METHOD의 알맞은 역할
POST, GET, PUT, DELETE 이 4가지의 Method를 가지고 CRUD를 할 수 있습니다.

METHOD역할

POST	POST를 통해 해당 URI를 요청하면 리소스를 생성합니다.
GET	GET를 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	PUT를 통해 해당 리소스를 수정합니다.
DELETE	DELETE를 통해 리소스를 삭제합니다.

---

REST API의 작동 방식

REST API의 작동 방식은 HTTP 프로토콜을 기반으로 합니다. REST API는 HTTP 요청을 통해 데이터를 주고 받습니다. REST API는 자원(resource)을 URI(Uniform Resource Identifier)로 표현합니다. 각 URI는 HTTP 메소드를 사용하여 자원에 대한 접근 및 처리를 제어할 수 있습니다. 예를 들어, URI를 통해 사용자 리스트를 조회할 수 있는 API에서는 HTTP GET 메소드를 사용하고, 새로운 사용자를 생성할 수 있는 API에서는 HTTP POST 메소드를 사용합니다.

---

REST API를 디자인하는 방법

REST API를 작성할 때는 몇 가지 지켜야 할 규칙들이 있습니다. 로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었습니다.

REST 성숙도 모델 - 0단계(Level 0)

REST 성숙도 모델에 따르면, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 됩니다. 물론 이 경우, 해당 API를 REST API라고 할 수는 없으며, 0단계는 REST API를 작성하기 위한 기본 단계입니다. 단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점입니다.

Level 0은 웹 매커니즘을 사용하지 않고 HTTP를 원격 호출을 위한 전송 시스템으로 사용하는 경우이다. RPC(Remote Procedure Call)처럼 리소스 구분 없이 설계된 HTTP API입니다.

하나의 End-point를 사용해서 HTTP Method도 반드시 POST가 된다. 그래서 서로 다른 매개변수를 통해서만 여러 동작을 하게 됩니다.

//Request

POST /api/user
{
  "function": "getUser",
  "arguments" [
    "1"
  ]
}
 

//Response

HTTP/1.1 200 OK
{
  "result" {
    "id": "1"
    "name": "honey",
  }
}
 

CRUD

CREATE : POST /api/user
READ :   POST /api/user
UPDATE : POST /api/user
DELETE : POST /api/user

REST 성숙도 모델 - 1단계(Level 1 : Resources)

REST 성숙도 모델 1단계를 이해하고 나면 앞의 0단계에서 들었던 API 예시를 조금 더 적절하게 바꿀 수 있을 것입니다. REST 성숙도 모델에 따르면, 1단계에서는 개별 리소스(Resource)와의 통신을 준수해야 합니다.

조금 더 쉽게 말하면, 앞서 REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다고 이야기했습니다. 따라서 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계의 핵심입니다.

1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용합니다.

Level 1은 리소스 개념을 도입합니다.  모든 요청을 하나의 End-point로 보내는 것이 아니라 개별 리소스와 통신하게 됩니다.

HTTP Method는 GET과 POST만 사용하고 StatusCode는 무조건 200으로 전달한다. 헤더에 Content-Type이나 Cache 관련 정보도 제공하지 않습니다.

// Request

POST /api/users/create
{
  "name": "honey"
}


// Response

HTTP/1.1 200 OK
{
  "result" {
    "error": "already exist member"
  }
}
CRUD

CREATE : POST /api/users/create
READ :   GET /api/users/1
UPDATE : POST /api/users/update
DELETE : POST /api/users/remove/1

REST 성숙도 모델 - 2단계 (Level 2 : HTTP Verbs)

REST 성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둡니다. 앞서 0단계와 1단계 예시에서는 모든 요청을 CRUD(Create, Read, Update, Delete)와 상관없이 POST 메서드를 사용하고 있습니다. 그러나 REST 성숙도 모델 2단계에 따르면, 이는 CRUD에 따른 적합한 메서드를 사용한 것이 아닙니다.

Level2는 4가지 HTTP Method를 사용해서 CRUD를 표현하고 StatusCode도 활용하여 반환합니다.

URI에는 행위(Action)가 포함되지 않고 HTTP Method로 표현한다. GET은 매번 같은 결과를 반환하고, 헤더에 Content-Type을 제공하고 멱등성을 보장하는 GET의 경우 캐시가 적용됩니다.

현재 가장 많은 REST API가 이 단계에 해당한다고 합니다.

//Request

POST /api/users
{
  "name": "honey"
}


//Response

HTTP/1.1 201 Created
Content-Type: application/json
{
  "result" {
    "id": "1",
    "name": "honey"
  }
}
CRUD

CREATE : POST /api/users
READ :   GET /api/users/1
UPDATE : PUT /api/users/1
DELETE : DELETE /api/users/1

 

REST 성숙도 모델  3단계는 잘 사용하지 않아 생략

---

HTTP 응답 상태 코드 

HTTP 상태 코드 - HTTP | MDN

응답 상태코드를 간단히 살펴보도록 하겠습니다. 잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 합니다. 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것은 생각보다 중요한 일이 될 수도 있습니다. 혹시 200이나 4XX관련 특정 코드 정도만 사용하고 있다면 처리 상태에 대한 좀 더 명확한 상태코드 값을 사용할 수 있기를 권장하는 바입니다. // 아래 주요 상태코드 

상태코드

200	클라이언트의 요청을 정상적으로 수행함
201	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)

상태코드

400	클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
401	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
	(로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)
403	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
	(403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에)
405	클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드
409	이 응답은 요청이 현재 서버의 상태와 충돌될 때 보냅니다.

상태코드

301	클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드
	(응답 시 Location header에 변경된 URI를 적어 줘야 합니다.)
500	서버에 문제가 있을 경우 사용하는 응답 코드

---

REST API의 장단점

REST API의 장점은 다양한 플랫폼과의 연동성 및 높은 확장성입니다. 또한, REST API는 다양한 언어와 프레임워크에서 구현하기 쉽고 개발 비용이 적게 들기 때문에 사용하기에 좋습니다. 하지만, REST API의 단점으로는 안정성이 떨어지는 경우가 있으며, 적은 양의 데이터만 주고 받을 수 있기 때문에 대용량 데이터를 처리하는 경우에는 적합하지 않을 수 있습니다.

---

정리

REST API는 HTTP 프로토콜을 기반으로한 API로, 다양한 플랫폼과의 연동성 및 확장성이 높다는 장점을 가지고 있습니다. HTTP의 기본 요청 메소지를 사용하여, 웹 리소스를 CRUD(Create, Read, Update, Delete) 작업을 수행할 수 있습니다. REST API는 다양한 기술 스택과 플랫폼에서 사용 가능하며, 쉽게 개발할 수 있지만, 대용량 데이터 처리 능력이 떨어질 수 있습니다.

최종적으로, REST API는 웹 개발에서 간편하고 확장성이 높은 데이터 전송 방식으로 자주 사용됩니다.

그리고 REST API의 2단계(HTTP 메소드 제공)는 가장 많이 사용되는 이유는 다음과 같습니다:

1. 쉬운 이해: HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하면 API의 기능이 명확하게 표시되어 개발자들이 쉽게 이해할 수 있습니다.
2. 표준적인 사용: HTTP 메소드는 웹 개발 분야에서 표준적으로 사용되는 것이기 때문에, REST API에서도 널리 사용되고 있습니다.
3. 안정적인 구조: HTTP 메소드는 안정적인 구조를 제공하여 API의 기능이 예측 가능하고 안정적이며, 데이터를 제어하는 것이 쉽습니다.
4. 다양한 기능 활용: HTTP 메소드는 다양한 기능을 활용할 수 있는 것이 장점입니다. 예를 들어, GET 메소드는 데이터를 조회하는 기능, POST 메소드는 데이터를 생성하는 기능 등을 제공합니다.

따라서, REST API의 2단계(HTTP 메소드 제공)는 REST API 개발에서 가장 많이 사용되는 이유이기 때문에 효율적인 API 개발 및 유지 보수를 위해서는 REST API 2단계(HTTP 메소드 제공)를 고려해야 합니다.

REST API 2단계를 사용하면 API 구조가 명확하고 안정적으로 구성되어, 개발자가 API의 기능을 쉽게 이해하고 구현할 수 있습니다. 또한, 다양한 기능을 활용할 수 있기 때문에, API를 유지 보수하는데 효율적입니다.

---

OpenAPI

오픈API란?

오픈API란 누구나 사용할 수 있도록 공개된 API를 말합니다. 데이터를 표준화하고 프로그래밍해 외부 소프트웨어 개발자나 사용자가 바로 개발(어프리케이션)에 활용할 수 있는 형태의 개방 형식입니다. 개방된 오픈API를 이용해 다양하고 재미있는 서비스나 애플리케이션, 다양한 형태의 플랫폼을 개발할 수 있습니다. (*API란? Application Programming Interface)

OpenAPI는 REST API를 정의, 구조화하는 스펙입니다. OpenAPI 스펙은 API의 구조, 요청/응답 메시지 형식, 지원하는 HTTP 메소드, 입력/출력 파라미터 등을 기술하고 공유할 수 있도록 합니다.

OpenAPI 스펙을 이용하면 API 개발자와 클라이언트 개발자 사이에서 협업하는데 많은 편의성을 제공합니다.

공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있습니다. 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있습니다.

OpenAPI 예시:

openapi: 3.0.0
info:
  title: Sample API
  description: A sample API using OpenAPI specification
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      description: Get a list of users
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      description: Create a new user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        201:
          description: Successful response
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

OpenAPI 스펙을 사용하고 싶으시다면, 관련 사이트를 참고하시면 좋습니다.

• OpenAPI 공식 사이트: https://www.openapis.org/
• Swagger: https://swagger.io/ (OpenAPI 구현 도구)
• ReDoc: https://redoc.ly/ (OpenAPI 구현 도구)
• 정부 공공데이터포털 https://www.data.go.kr/

---

API 키를 사용하는 이유 및 조건

 

API 키는 프로젝트용, 인증은 사용자용

Cloud Endpoints는 API 키와 인증 체계(Firebase 또는 Auth0)를 모두 처리합니다. 다음은 API 키와 인증의 주된 차이점입니다.

• API 키는 호출하는 프로젝트, 즉 API를 호출하는 앱이나 사이트를 식별합니다.
• 인증 토큰은 사용자, 즉 앱이나 사이트를 사용하고 있는 사람을 식별합니다.

API 키는 프로젝트 승인 제공

가장 적절한 체계를 결정하려면 API 키와 인증에서 무엇을 제공하는지 이해하는 것이 중요합니다.

API 키는 다음을 제공합니다.

• 프로젝트 식별 — API를 호출하는 애플리케이션이나 프로젝트를 식별합니다.
• 프로젝트 승인 — 호출하는 애플리케이션에 API를 호출하는 액세스 권한이 부여되었고 프로젝트에서 API가 사용 설정되었는지 여부를 확인합니다.

API 키는 인증 토큰만큼 안전하지 않지만(API 키의 보안 참조), API를 호출하는 애플리케이션이나 프로젝트를 식별합니다. 이러한 키는 호출을 수행하는 프로젝트에서 생성되며 특정 IP 주소 범위, Android 앱, iOS 앱과 같은 환경에서 키 사용을 제한할 수 있습니다.

호출하는 프로젝트를 식별하면 API 키를 사용하여 사용 정보를 해당 프로젝트와 연결할 수 있습니다. Extensible Service Proxy(ESP)는 API 키를 사용하여 액세스 권한을 부여받지 못했거나 API에서 사용 설정되지 않은 프로젝트의 호출을 거부할 수 있습니다.

API 키 사용 조건

API에서 해당 메소드의 일부 또는 모두 API 키가 필요하도록 제한할 수 있습니다. 이는 다음과 같은 경우 유용합니다.

• 익명 트래픽을 차단하려 합니다. 문제를 디버그하거나 애플리케이션 사용량을 표시하기 위해 애플리케이션 개발자가 API 제작자와 협력해야 하는 경우, API 키로 API 제작자의 애플리케이션 트래픽을 식별합니다.
• API 호출 수를 제어하려고 합니다.
• API 트래픽의 사용 패턴을 식별하려 합니다. API 및 서비스에서 애플리케이션 사용량을 볼 수 있습니다.
• API 키를 기준으로 로그를 필터링하려고 합니다.

API 키를 다음 용도로 사용할 수 없습니다.

• 개별 사용자 식별 - API 키는 사용자를 식별하지 않고 프로젝트를 식별합니다.
• 안전한 승인
• 프로젝트 제작자 식별

 

정리

가장 기초적인 방법으로 서비스 제공자가 발급해준 KEY를 통해 인증을 하는 방식이다.
- API Key는 특정 사용자만 알 수 있는 일종의 문자열로 되어 있다. (예:aASDFasdf87AS5D4F2asddf234SDF234)
- API Key는 API 서비스 제공자가 제공하고 사용자는 API Key 정보를 메시지 안에 포함하여 호출한다.
- API Key는 한번 노출되면 전체 API가 뚫리는 문제가 발생할 수 있기 때문에 높은 보안 인증이 필요한 상황에는 적합하지 않는 방법이다.

---

 

https://cloud.google.com/endpoints/docs/openapi/when-why-api-key?hl=ko

https://aws.amazon.com/ko/what-is/api/

https://jaehoney.tistory.com/176