API와 그 구조 이해하기

Source: Dev.to

API란 무엇인가요?

API는 Application Programming Interface(한국어: 응용 프로그램 인터페이스)를 의미합니다.
기본적으로 API는 한 시스템이 다른 시스템과 대화할 수 있게 해 주는 방법으로, 정보를 조직적으로 교환하고 미리 정의된 규칙을 따릅니다. 한 시스템이 다른 시스템으로부터 데이터를 가져오거나, 정보를 전송하거나, 무언가를 생성·수정하고 싶을 때, API가 그 다리를 놓아 줍니다.

REST API에 대해 이야기할 때, 이들은 HTTP/HTTPS를 사용해 통신합니다. 이는 브라우저가 사용하는 프로토콜과 동일합니다. 모든 작업은 URL인 **엔드포인트(endpoint)**를 통해 이루어집니다.

• 엔드포인트: API 서비스가 제공되는 주소.
• Request → Response: API는 요청을 받고 데이터를 반환하거나, 확인 메시지 혹은 오류를 반환합니다. 이때 항상 상태 코드와 함께 반환됩니다(예: 200 – OK).

일반적인 HTTP 메서드

데이터 포맷

대부분의 최신 API는 JSON을 데이터 교환 포맷으로 사용합니다:

{
  "exemplo": "valor",
  "lista": [1, 2, 3]
}

JSON은 가볍고 읽기 쉬우며 거의 모든 프로그래밍 언어와 잘 호환됩니다.

요청 헤더 (Headers)

헤더는 API가 요청을 처리하는 데 필요한 추가 정보를 담고 있습니다. 예시:

• 콘텐츠 타입 (Content-Type: application/json)
• 인증 토큰
• 언어 (Accept-Language)
• 권한 정보

올바른 헤더가 없으면 많은 API가 접근 자체를 차단합니다.

인증

모든 API가 공개된 것은 아니며, 대부분은 권한 확인이 필요합니다. 흔히 사용되는 인증 방식은 다음과 같습니다:

• API Key
• Bearer Token
• JWT (JSON Web Token)
• OAuth2

버전 관리

API는 시간이 지나면서 진화하기 때문에 URL에 버전을 포함시키는 것이 일반적입니다:

/api/v1/clientes

Spring Boot으로 간단한 API 만들기

Spring Initializr를 이용하면 빠르게 API를 만들 수 있습니다.

기본 단계

1. Spring Initializr에 접속해 원하는 의존성을 선택해 프로젝트를 생성합니다(예: Spring Web).
2. IDE에 프로젝트를 임포트합니다.
3. REST 컨트롤러를 작성합니다:

// src/main/java/com/exemplo/DemoController.java
package com.exemplo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/api/v1/hello")
    public String hello() {
        return "Olá, mundo!";
    }
}

4. 애플리케이션을 실행합니다(./mvnw spring-boot:run 혹은 IDE를 통해) 그리고 http://localhost:8080/api/v1/hello 엔드포인트에 접속합니다.

유용한 링크

• Spring Initializr: https://start.spring.io
• 저자 LinkedIn 프로필: (링크 제공되지 않음)