[API] 개요 / RESTful 설계규칙 / HTTP 메소드

API

프론트/백단으로 분리되게 되면 API가 백단의 역할을 맡게 된다.

API란 무엇인지 간단하게 훑어본다.

---

API란?

• Application Programming Interface
  소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청, 명령을 받을 수 있는 수단
• 장점
  - 데이터 접속의 표준화와 편의성(디바이스/운영체제 등과 상관없이 조건만 맞다면 동일한 액세스 가능)
  - 자동화와 확장성(API를 통한 CRUD처리)
  - 적용력(예측성이 높아 유연한 서비스 제공 가능)
• 단점
  - HTTP방식으로 인한 보안의 취약점(SQL injection, DDoS, .. 등)
  - 공식화된 표준의 부재로 관리가 어렵고 광범위한 프로그래밍 지식 필요

 

 

접근방식에 따른 API종류

• Private API
  내부 API로 제삼자에게 노출되지 않는다
• Public API
  개방형 API로 이중에서도 접속하는 대상에 대한 제약이 없는 경우를 OpenAPI라고 한다
  * OpenAPI 예시
  - 구글 : https://cloud.google.com/apis?hl=ko
  - 공공데이터포털 : https://www.data.go.kr/
  - 문화데이터 광장 : https://www.culture.go.kr/data/main/main.do
  - 카카오 : https://developers.kakao.com/tool
• Partner API
  특정 비즈니스 파트너간의 데이터 공유

 

 

아키텍처 스타일에 따른 API종류

• 클라이언트 : 요청을 보내는 어플리케이션
  서버 : 응답을 보내는 어플리케이션
• SOAP API
  - Simple Object Access Protocol
  - 클라이언트와 서버는 XML을 사용하여 메세지 교환
  - 유연성이 떨어져 현재에는 많이 쓰이지 않는다
• Websocket API
  - JSON객체를 사용하여 데이터를 전달
  - 클라이언트와 서버간의 양방향 통신을 지원
  - 서버가 연결된 클라이언트에 콜백메세지를 전송할 수 있다는 점에서 REST API 보다 효율적
• REST API
  - 과거 SOAP 방식의 복잡한 형식을 대체하며 최근 웹에서 가장 많이 볼 수 있는 유연한 API
  - 클라이언트의 요청은 웹사이트에 방문하기 위해 브라우저에 입력하는 URL과 유사한 형태를 갖는다.
  - Web API라고도 불린다.

 

---

REST API

URI와 HTTP메소드의 개념을 짚어보고 REST API를 간단히 실습해본다.

---

URI vs URL

• URI
  - Uniform Resource Identifier
  - 인터넷상의 리소스 자원을 식별하는 고유한 문자열 시퀀스
  - 암묵적 규칙이 있어서 해석이 가능하다 
  ex) http://(도메인)/classes/2/student : 2번반의 학생들에 대한 접근이라고 예상 가능
• URL
  - Uniform Resource Locator
  - 네트워크상의 리소스의 위치를 나타내는 규약
  - URI에 위치정보가 덧붙여진 개념, URI의 일종으로 볼 수 있다.

 

REST API 개요

• REST API란?
  - REST의 원리를 따라는 API.
  - Representational State Transfer
    자원을 이름으로 구분하여 해당 자원의 상태로 주고 받는다.
  1. HTTP URI를 통해 자원(Resource)을 명시하고
  2. HTTP Method(POST, GET, PUT, DELETE, .. 등)를 통해
  3. 해당 자원(URI)에 대한 CRUD를 진행한다.
• REST 구성요소
  - 자원(Resource) : HTTP URI
  - 자원에 대한 행위(Verb) : HTTP Method
  - 행위의 내용(Representations) : HTTP Message Pay Load
• 장점
  - HTTP 프로토콜의 인프라를 그대로 사용하므로 별도의 인프라를 구출할 필요가 없다.
  - HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능
  - REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
  - 서버와 클라이언트의 역할을 명확하게 분리한다.
• 단점
  - 표준이 자체가 존재하지 않아 정의가 필요하다.
  - HTTP Method 형태가 제한적이다.
  - 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
  - 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)

 

 

HTTP 메소드

• HTTP Method는 주로 GET, POST, PUT, DELETE가 쓰인다.
• GET이나 POST 하나로도 CRUD가 가능하지만 RESTful하게 API를 만들기 위해서 각 메소드를 이용 목적에 따라 구분해서 사용한다.
• 이때, 데이터 전달 방식로 두가지로 분류할 수 있다.
• Body가 없어서 URL을 통해서 값을 받음
  - GET : select 용도. 
  - DELETE : delete 용도
• Body가 있음
  >> GET이나 DELETE보다 정보를 많이, 비교적 안전하게 감춰서 보낼 수 있다
  - POST : create용도
  - PUT : update용도 (정보를 통채로 수정할때), 이 메소드를 쓰면 POST를 쓸때와 달리 Idempotence(여러번 수행해도 결과가 같음) 특성이 생긴다.

 

 

요청방법별 사용할수있는 메소드

• 요청 방법에 따라 데이터를 받는 방법이 달라진다.
• URL(주소창, 하이퍼링크)
  GET
• form태그
  GET, POST
• 자바스크립트
  GET, POST, DELETE, PUT

 

 

설계 규칙

• URI는 동사보다는 명사를, 대문자보다는 소문자를 사용하여야 한다.
  Bad example : http://yes-p.com/Run
• 마지막에 슬래시(/)를 포함하지 않는다.
  Bad example : http://yes-p.com/test/
• 언더바 대신 하이픈을 사용한다.
  Good example :  http://yes-p.com/test-blog
• 파일확장자는 URI에 포함하지 않는다.
  Bad example :  http://yes-p.com/test.png
• 행위를 포함하지 않는다
  Bad example : http://yes-p.com/delete-post

 

 

REST 설계 예시 (spring)

1. 컨트롤러 어노테이션 붙여주기
   - @RestController 를 컨트롤러 역할을 할 클래스 선언부에 붙여준다.
     @Controller에 @ResponseBody가 결합된 어노테이션으로
     하위 메소드에 @ResponseBody를 붙이지 않아도 문자열과 JSON 등을 전송할 수 있다.  
     * @ResponseBody  : 리턴값이 응답뷰가 아닌 데이터라는 선언
2. URI 구분하기
   - 클래스 선언부에 1차적으로 @RequestMapping("/dto종류")를 붙여 대분류를 하고,
   각 메소드별로 2차적으로 @RequestMapping("/메소드의역할")을 붙여 역할을 세분화한다.
3. 각 메소드별로 HTTP 메소드 부여하기
   - 스프링 4.3 버전부터 @RequestMapping(value="/메소드역할", method="{RequestMethod.POST}")을 대체할 수 있는 어노테이션이 추가되었다.
   >> @PostMapping, @GetMapping, @PutMapping, @DeleteMapping, @PatchMapping 
   - 해당 어노테이션을 사용하면 uri만 입력해주면 된다.

@RestController
@RequsetMapping("/user")
public class UserController {
    
    @PostMapping("/join")
    public String createUser(@RequestBody User user) {
        // 로직실행..
        return "User created successfully!";
    }
    ...
}