본문 바로가기
Spring/Web

RESTful API & HTTP

jsjhyun 2024. 5. 23. 13:51

 

웹 서비스 구조

HTTP socket을 segment로 나눠서 Packet 형태로 모아 전송

  •  TCP/IP - HTTP를 통해 Client와 Web의 연결

Client가 URL를 통해 페이지 요청(GET) → Web에서 Html 문서 뷰어 + (CSS)를 보냄

Html + CSS(정적) + JS(동적)

POST 등장으로 양방향 상호작용 가능

상태 전이를 위해 클라이언트와 서버 쪽 모두 기억해야 할 것이 생김 → 클라이언트 쪽: Cookie 서버 쪽: DB

 

REST란?

Representational State Transfer라는 용어의 약자로서 웹의 장점을 최대한 활용할 수 있는 아키텍처

 

API란?

많은 개발자들이 데이터와 상호작용을 하기 위한 인터페이스

 

용어

  • Resource : 어떤 것의 대표 혹은 객체이다. 이는 관련 데이터를 갖고 있고, 이를 운용하기 위한 메소드 집합을 가질 수 있다. 예: Animals, schools, employees는 resources이고 delete, add, update는 이 resources에서 수행되는 operations이다.
  • Collections : resources의 집합이다. 예: Companies는 Company resource의 집합이다.
  • URL (Uniform Resource Locator) : 어느 resource가 어디에 위치할 수 있고 어떤 action들이 수행될 수 있는 지를 나타내는 경로이다.

REST API 란 ?

  • HTTP URL을 통해 자원을 명시하고 HTTP Method (POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD OPERATION을 적용하는 것을 의미한다.
  • 웹의 모든 자원에 고유한 ID인 HTTP URI를 부여한다.
  • 플랫폼에 맞추어 새로운 서버를 만드는 수고를 들이지 않기 위해 범용적으로 사용성을 보장하는 서버 디자인이다.

 

Restful api 만드는 이유

  • Client Side를 정형화된 플랫폼이 아닌 모바일, PC, 어플리케이션 등 플랫폼에 제약을 두지 않는 것을 목표로 한다.
  • 메시지 기반, XML, JSON과 같은 Client에서 바로 객체로 치환 가능한 형태의 데이터 통신을 지향하게 되면서 Server와 Client의 역할을 분리한다.

REST의 구성

  • 자원(Resource) : URL
  • 행위(Verb) : Http Method
  • 표현(Representations)

 

자원 (Resource) - URL

  • 모든 자원에 고유한 ID가 존재하고 이 자원은 Server에 존재한다.
  • 자원을 구별하는 ID는 /orders/order_id/1 와 같은 HTTP URI이다.

예시)

https://(도메인)/classes/2 → 학원 반 목록을 받아오는 요청 → 초급 반의 정보가 온다.

{
"results" : [
		{"idx": 1, "name": "예비반"},
		{"idx": 2, "name": "초급반"},
		{"idx": 3 , "name": "중급반"},
	]
{

 

행위 (Verb) - Http Method

  • HTTP 프로토콜의 Method를 사용한다.
  • HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다.

 

표현 (Representaion of Resource)

  • Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답을 보낸다.
  • REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태로 나타낼 수 있다.
  • 현재는 JSON으로 주고 받는 것이 대부분이다.

 

HTTP METHOD의 알맞는 역할

  • POST : POST를 통해 해당 URL를 요청하면 리소스를 생성한다.
  • GET : GET를 통해 해당 리소스를 조회한다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
  • PUT : PUT을 통해 해당 리소스를 모두 수정한다.
  • DELETE : DELETE를 통해 리소스를 삭제한다.
  • PATCH : 정보 중 일부를 특정 방식으로 수정할 때 사용한다.

특징

  • BODY에 CRUD 정보 요청 작성
  • GET. DELETE 보다 POST. PUT. PATCH가 비교적 안전하게 감춰서 실어 보낸다.

예시

  • 몇 가지 다른 사용 사례에서 resource 아래에 여러 개의 resources가 있는 경우 (예 : 회사의 직원들), API endpoint(API 호출이 수행되는 곳)는 아래와 같을 수 있다.
  • GET /companies/3/employees 는 company 3에 속하는 employees 전체 목록을 가져온다.
  • GET /companies/3/employees/45 는 company 3에 속하는 employee 45의 상세 내용을 가져온다.
  • DELETE /companies/3/employees/45 는 company 3에 속하는 employee 45를 삭제한다.
  • POST /companies 는 새로운 company를 생성하고 생성된 company의 상세 내용을 리턴한다.

 

HTTP 상태 코드

클라이언트가 보낸 요청의 처리 상태를 응답에서 알려주는 기능

 

2XX : 요청 정상 처리

200 : OK

201 : 서버가 리소스 생성..Location : /members/100

204: 저장 시 보낼 데이터 없음

 

3XX : 요청을 완료하려면 추가 행동이 필요. 리다이랙트 사용 시

 

4XX : 클라이언트 오류

 

5XX : 서버 오류

 

 

특징

 

클라이언트 / 서버 구조

  • 클라이언트는 유저와 관련된 처리를 하고 서버는 REST API를 제공함으로써 각각의 역할이 확실하게 구분되고 일괄적인 인터페이스로 분리되어 작동할 수 있게 한다.
  • REST Server : API를 제공하고 비지니스 로직 처리 및 저장을 책임진다.
  • Client : 사용자 인증이나 context (세션, 로그인 정보) 등을 직접 관리하고 책임진다.

무상태성

  • REST는 HTTP의 특성을 이용하기 때문에 무상태성을 갖는다. 즉 서버에서 어떤 작업을 하기 위해 상태 정보를 기억할 필요가 없고 들어온 요청에 대해서만 처리해주면 되기 때문에 구현이 쉽고 단순해진다.

캐시 처리 가능

  • HTTP라는 기존 웹 표준을 사용하는 REST의 특징 덕분에 기본 웹에서 사용하는 인프라를 그대로 사용 가능하다.
  • 대량의 요청을 효율적으로 처리하기 위해 캐시가 요구된다.

자체 표현 구조

  • JSON을 이용한 메시지 포멧을 이용하여 직관적으로 이해할 수 있고 REST API 메시지만으로 그 요청이 어떤 행위를 하는지 알 수 있다.

기타 특징

  • 각 요청이 어떤 동작이나 정보를 위한 것인지 요청의 모습 자체로 추론이 가능하다.
  • Restful하게 만든 API는 요청을 보내 주소만으로도 무엇을 하는지 대략 유추 가능하다.
  • URL은 오직 resources(명사)만 포함해야 하며 동사나 actions를 포함해서는 안된다.
  • GraphQL이 대안으로 떠오르고 있다.

 

규칙

 

중심 규칙

  • URL은 정보의 자원을 표현해야 한다.
  • 자원에 대한 행위는 HTTP Method (GET, POST, PUT, DELETE 등)으로 표현한다.

세부 규칙

  • 슬래시 구분자 ( / )는 계층 관계를 나타내는데 사용한다.
  • URI 마지막 문자로 슬래시 ( / )를 포함하지 않는다.
  • 하이픈 ( - )은 URI 가독성을 높이는데 사용한다.
  • 밑줄 ( _ )은 URI에 사용하지 않는다.
  • URI 경로에는 소문자가 적합하다.
  • 파일확장자는 URI에 포함하지 않는다.

 

Swagger

스웨거란 RESTAPI 개발시 문서를 자동으로 만들어주는 프레임워크이다.

Request 날릴때 사용한다.

postman을 사용해도 되고 이 swagger를 사용해도 좋다.

gradle인 경우 라이브러리에 추가해야 한다.

 

OrderRequest/Response: 송/수신 DTO 파일

Controller에 @ApiOperation 어노테이션을 API에 추가해 API에 대한 주석을 달 수 있음(옵션)

Response용 DTO에 @ApiModelProperty

public class OrderResponse {    
@ApiModelProperty(example = "Order id")    
private String id = null;    

@ApiModelProperty(example = "주문 수량")    
private int quantity = 0;    

@ApiModelProperty(example = "주문 일자")    
private String date = null;    

@ApiModelProperty(example = "주문 상태")    
private String status = null;    

@ApiModelProperty(example = "주문 완료 여부")    
private boolean complete = false;

기본 세팅법

의존성 추가, 설정 추가

SwaggerConfig.class

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String API_NAME = "Study API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Study API 명세서";

    @Bean
    public Docket api() {
        Parameter parameterBuilder = new ParameterBuilder()
            .name(HttpHeaders.AUTHORIZATION)
            .description("Access Tocken")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(false)
            .build();

        List<Parameter> globalParamters = new ArrayList<>();
        globalParamters.add(parameterBuilder);

        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(globalParamters)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kjh.study.api"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
	return new ApiInfoBuilder()
		.title(API_NAME)
		.version(API_VERSION)
		.description(API_DESCRIPTION)
		.build();
    }
}

 

api 작성 예제 https://petstore.swagger.io

 

Swagger UI

 

petstore.swagger.io

 

Postman

API 개발을 보다 빠르고 쉽게 구현 할 수 있도록 도와주며, 개발된 API를 테스트하여 문서화 또는 공유 할 수 있도록 도와 주는 플랫폼

 

GET은 단순하게 확인이 가능하지만 post / put / delete 등 HTTP의 응답을 확인하기 위해 별도의 작업이다.

GET : 데이터를 주소에 붙여서 보내기

 

POST

raw, JSON 선택

@RequestBody

@RestController

Collections에 API URL을 추가한다.

API 추가 (요청 준비) NEW - Request - name(임의) - Collection명 정하고 체크 - Save 결과 확인하기 요청방식. URL 짝 맞게 메소드 설정 - URL 입력하고 Send -> Response 표시

+ 버튼으로 새탭을 열어 요청정보 추가 가능 새로 연 탭은 Save 버튼으로 Collection에 저장이 가능

'Spring > Web' 카테고리의 다른 글

HTTP  (0) 2024.05.23

'Spring/Web' Related Articles

티스토리툴바