API와 REST API

 

 

API (Application Programming Interface)

소프트웨어 애플리케이션 간에 서로 통신하고 데이터를 주고받을 수 있도록 하는 규칙 집합!

 

Interface

인터페이스란? 하나의 사물이 다른 사물과 상호 작용하는 방법이다. 

CLI, GUI에서 사용하듯! 인터페이스는 '매개체'의 의미를 가진다.

 

REST API

REST API 는 REST원칙을 따르는 API, HTTP 규약을 잘 따른 API다.

아래의 글에 REST API와 URI에 대해 상세히 정리한 바 있다.

https://yesolz.tistory.com/entry/REST-API-URI-%EC%84%A4%EA%B3%84-%EA%B7%9C%EC%B9%99

REST API URI 설계 규칙

REST API vs RESTful API?
RESTful API가 REST 아키텍처를 더 충실히 완벽하게 따른 API임을 강조하는 표현이라고 볼 수 있다.
즉, RESTful API ⊆ REST API 

 

 

HTTP method

• 생성(=등록): POST
• 조회: GET
• 수정: PUT(덮어쓰기) / PATCH(부분 수정)
• 삭제: DELETE
• HEAD, OPTIONS, CONNECT, TRACE - 데이터 외의 것들에 사용.

 

 

REST API URL 규칙

• 대문자 x, 소문자 o
• 언더바(_) x, 하이픈(-) o
• 마지막에 / 포함 x
• 행위나 목적을 포함하지 않는다
• 파일 확장자 포함 x
• 복수형을 쓴다

 

이 중 헷갈릴 수 있는 부분 몇 개만 상세히 정리해보겠다!

 

행위나 목적을 포함하지 않는다

REST API의 URL은 리소스를 명확하게 식별하는 데 사용된다.

이 원칙에 따라, URL은 리소스에 대한 행위(ex. create, delete, update)나 목적(ex. save, download)를 명시적으로 포함하지 않는다. 

이러한 행위나 목적은 HTTP 메서드를 사용하여 표현하기 때문이다. 

HTTP 메서드는 이미 각기 다른 행위를 표현하기 위해 존재하기 때문에, URL에 행위를 포함할 필요가 없다.

• 잘못된 예시: /create-user
• -> /users로 하고, HTTP POST 메서드를 사용하여 새로운 사용자를 생성하면 된다. 

 

파일 확장자 포함 x

사용자 목록을 JSON 형식으로 제공하는 API를 /users.json 형식으로 제공하면 어떤 문제가 생길까?

-> URL이 특정 형식(JSON)에 종속적이다. 만약 XML 형식의 응답을 요청하려면, 별도의 URL(/users.xml)을 만들어야 하므로 매우 비효율적이다.

REST의 기본 원칙 중 하나는 리소스와 그 리소스에 대한 표현(형식)을 분리하는 것인데, 파일 확장자를 포함하면 리소스의 표현 방식이 URL에 고정되어 버린다. 

 

데이터 형식은 URL이 아닌 HTTP 헤더를 통해 지정된다.

예를 들어, 클라이언트는 Accept 헤더를 통해 서버에게 어떤 형식의 응답을 원하는지 지정할 수 있다. 

위의 예시를 이어서 들어보면,

요청은 GET /users로 하되

헤더에 Accept: text/html, Accept: application.json 등을 이용하여

서버에 어떤 형식의 응답을 원하는지 지정할 수 있는 것이다. 

 

복수형을 사용한다

REST API 에서는 리소스를 나타내는 경로에 복수형 명사를 사용한다.

이는 해당 경로가 특정 리소스 집합(collection)을 나타낸다는 것을 의미한다.

예를 들어 /products는 모든 상품들의 집합을 나타내는 것이다.

개별 리소스에 접근하려면, 해당 상품의 고유 식별자(ID)를 URL에 추가하여 지정할 수 있다. 이때도 기본 경로는 복수형을 유지한다.

 

REST API 설계 예시

1. 상품 전체 '조회' GET

/products

2. 상품 id 개별 '조회' GET

/products/{id}

3. 상품 id 개별 '수정' PUT

/products/{id}

 

ref
https://www.cloudflare.com/ko-kr/learning/security/api/what-is-an-api/

 

REST API의 원칙들을 알아가면서, 단순해 보이지만 그 안에 얼마나 큰 효율이 담겨 있는지 알게 되었다.

이런 규칙들을 통해 보다 효율적이고 견고한 API 설계에 기여하고 싶다.