📚 [Spring] Restful API, Entity & DTO

📕 Postman

Postman 설치

📖 Postman 실행 화면

✔ 🟥에 어떤 형식으로 URL을 요청할 건지 선택

✔ 🟥에 API URL을 작성하고 🟦에 Body로 보낼 값을 작성한 후 🟧을 누른다

📙 HTTP Method

◽ 클라이언트와 서버 사이에 이루어지는 요청(Request)과 응답(Response) 데이터를 전송하는 방식
◽ 서버에 주어진 리소스에 수행하길 원하는 행동, 서버가 수행해야 할 동작을 지정하는 요청을 보내는 방법

🎈 주요 메소드
GET : 리소스 조회
POST :  요청 데이터 처리, 주로 등록에 사용
PUT : 리소스를 대체(덮어쓰기), 해당 리소스가 없으면 생성
PATCH : 리소스 부분 변경 (PUT이 전체 변경, PATCH는 일부 변경)
DELETE : 리소스 삭제

🎈 기타 메소드
HEAD : GET과 동일하지만 메시지 부분(body 부분)을 제외하고, 상태 줄과 헤더만 반환
OPTIONS : 대상 리소스에 대한 통신 가능 옵션(메소드)을 설명(주로 CORS에서 사용)
CONNECT : 대상 자원으로 식별되는 서버에 대한 터널을 설정
TRACE : 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행

📖 GET 메소드

◾ 리소스 조회 메소드 (Read)
◾ 만일 틀서버에 전달하고 싶은 데이터는 쿼리스트링를 통해서 전달
GET /members/100?username=inpa&height=200
◾ 쿼리스트링 외에 메시지 바디를 사용해서 데이터를 전달할 수 있지만, 서버에서 따로 구성해야 되기 때문에 지원하지 않는 곳이 많아서 권장하지 않음
◾ 조회할 때 POST도 사용할 수 있지만, GET 메소드는 캐싱이 가능하기에 GET을 사용하는 것이 유리하다.

📖 POST 메소드

◾ 전달한 데이터 처리/생성 요청 메소드 (Create)
◾ 메시지 바디(body)를 통해 서버로 요청 데이터 전달하면 서버는 요청 데이터를 처리하여 업데이트
◾ 전달된 데이터로 주로 신규 리소스 등록, 프로세스 처리에 사용
◾ 만일 데이터를 GET 하는데 있어, JSON으로 조회 데이터를 넘겨야 하는 애매한 경우 POST를 사용

📖 PUT 메소드

◾ 리소스를 대체(수정)하는 메소드 (Update)
◾ 만일 요청 메세지에 리소스가 있으면 덮어쓰고, 없으면 새로 생성한다.

/members/100 데이터가 존재하면 기존에 것을 완전 대체 한다.
/members/100 데이터가 없으면 대체 할게 없으니까 새로 생성한다.

◾ 데이터를 대체해야 하니, 클라이언트가 리소스의 구체적인 전체 경로를 지정해 보내주어야 한다.

POST /members : 멤버 새로 추가
PUT /members/100 : 100번째 멤버 수정

❓ 일부 리소스만 변경하길 원한다면? PATCH 메소드를 사용하자!

📖 PATCH 메소드

◾ 리소스 일부 부분을 변경하는 메소드 (Update)
◾ 만일 PATCH를 지원하지 않는 서버에서는 대신에 POST를 사용할 수 있다.

📖 DELETE 메소드

◾ 리소스 제거하는 메소드 (Delete)
◾ 상태코드는 대부분 200을 사용하고 상황에 따라 204를 사용한다.

📖 HEAD 메소드

◾ GET과 동일하지만 서버에서 Body를 Return 하지 않음
◾ 응답의 상태 코드만 확인할때와 같이 Resource를 받지 않고 오직 찾기만 원할때 사용 (일종의 검사 용도)
◾ 서버의 응답 헤더를 봄으로써 Resource가 수정되었는지 확인 가능

📖 TRACE 메소드

◾ 이 메서드도 일종의 검사용
◾ 서버에 도달 했을 때의 최종 패킷의 요청 패킷 내용을 응답 받을 수 있다.
◾ 요청의 최종 수신자는 반드시 송신자에게 200(OK) 응답의 내용(Body)로 수신한 메세지를 반송해야 한다.
◾ 최초 Client의 요청에는 Body가 포함될수 없다.

📖 OPTION 메소드

◾ 예비 요청(Preflight)에 사용되는 HTTP 메소드
◾ 예비 요청이란 본 요청을 하기 전에 안전한지 미리 검사하는 것이라고 보면 된다
◾ 서버의 지원 가능한 HTTP 메서드와 출처를 응답 받아 CORS 정책을 검사하기 위한 요청이다.

📖 Content-Type 헤더 종류

Content-Type: application/x-www-form-urlencoded
◾ Form의 내용을 HTTP 메시지 바디를 통해서 전송(key=value, 쿼리 파라미터 형식)
◾ 전송 데이터를 url encoding 처리
◾ 예) abc김 → abc%EA%B9%80

Content-Type: multipart/form-data
◾ 파일 업로드 같은 바이너리 데이터 전송 시 사용
◾ 다른 종류의 여러 파일과 Form의 내용 함께 전송 가능

Content-Type: application/json
◾ TEXT, XML, JSON 데이터 전송 시 사용

📒 RESTful API

◽ REST API에서 REST는 Representational State Transfer의 약자로 소프트웨어 프로그램 아키텍처의 한 형식이다
◽ 자원을 이름 (자원의 표현) 으로 구분하여 해당 자원의 상태 (정보)를 주고 받는 모든 것을 의미한다
◽ 월드 와이드 웹 (WWW) 과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식
◽ REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다

📖 REST 구성

◾ 자원(RESOURCE) - URI
◾ 행위(Verb) - HTTP METHOD
◾ 표현(Representations)

📖 REST의 특징

1) Uniform (유니폼 인터페이스)
◾ Uniform Interface는 Http 표준에만 따른다면 모든 플랫폼에서 사용이 가능하며, URI로 지정한 리소스에 대한 조작을 가능하게 하는 아키텍쳐 스타일을 말한다
◾ URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다
◾ 즉, 특정 언어나 기술에 종속되지 않는다

2) Stateless (무상태성)
◾ REST는 HTTP의 특성을 이용하기 때문에 무상태성 성격을 갖는다 -> 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다
◾ 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다

3) Cacheable (캐시 처리 가능)
◾ HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 사용 가능하다
◾ 따라서 HTTP가 가진 캐싱 기능이 적용 가능한다
◾ 캐시 사용을 통해 응답시간이 빨라지고 REST Server 트랜잭션이 발생하지 않기 때문에 전체 응답시간, 성능, 서버의 자원 이용률을 향상 시킬 수 있다

4) Self-descriptiveness (자체 표현 구조)
◾ REST API 메시지만 보고도 그 요청이 어떤 행위를 하는지 알 수 있다

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

6) Layered System (계층화)
◾ 클라이언트와 서버가 분리되어 있기 때문에 중간에 프록시 서버, 암호화 계층 등 중간매체를 사용할 수 있어 자유도가 높다

📖 REST API 디자인 가이드

🎈 REST API 중심 규칙

✔ URI는 정보의 자원을 표현해야 한다.

GET /members/delete/1

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

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

DELETE /members/1

-> 잘못된 URI를 HTTP Method를 통해 수정해 보면 위와 같이 수정할 수 있다

🎈 URI 설계 시 주의할 점

1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales

2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다

http://restapi.example.com/houses/apartments/ (❌)
http://restapi.example.com/houses/apartments (⭕)

3) 하이픈(-)은 URI 가독성을 높이는데 사용

4) 밑줄(_)은 URI에 사용하지 않는다
-> 밑줄 대신 하이픈(-)을 사용하는 것이 좋다

5) URI 경로에는 소문자가 적합하다
-> 대소문자에 따라 다른 리소스로 인식하게 되기 때문이다

6) 파일 확장자는 URI에 포함시키지 않는다

http://restapi.example.com/members/soccer/345/photo.jpg (❌)

-> REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다
-> 대신 Accept Header를 사용한다

GET / members/soccer/345/photo HTTP/1.1
Host: restapi.example.com
Accept: image/jpg

7) 리소스 간에 연관 관계가 있는 경우

/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유의 관계를 표현할 때)

만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다

//사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

📖 RESTful API

◽ RESTful이란, HTTP와 URI 기반으로 자원에 접근할 수 있도록 제공하는 애플리케이션 개발 인터페이스이다
◽ REST API를 제공하는 웹 서비스를 'RESTful'하다고 할 수 있다
◽ RESTful API란, REST의 설계 규칙을 잘 지켜서 설계된 API이다

📗 @RestController

◽ @RestController 어노테이션은 @Controller와 @ResponseBody가 합쳐진 형태로, REST API를 개발할 때 주로 사용된다
◽ 이 어노테이션을 컨트롤러 클래스에 적용하면, 모든 요청 매핑 메소드에서 반환되는 데이터는 기본적으로 JSON 형태의 객체 데이터로 처리된다
◽ 따라서 각 메소드에 @ResponseBody를 별도로 추가할 필요가 없게 된다

📘 Entity와 DTO

📖 Entity

🎈 회원 Entity

@Entity
@Getter @Setter
public class Member {
    @Id @GeneratedValue
    @Column(name = "member_id")
    private Long id;

    private String name;

    @Embedded
    private Address address;

    @OneToMany(mappedBy = "member")
    private List<Order> orders = new ArrayList<>();
}

✔ @Entity은 데이터베이스의 테이블과 일대일로 매칭되는 객체 단위이며, Entity 객체의 인스턴스 하나가 테이블에서 하나의 레코드 값을 의미하게 된다
✔ 객체의 인스턴스를 구분하기 위한 유일한 키 값을 가지는데 이것은 테이블 상의 Primary Key와 같은 의미를 가지며 @Id로 표기된다

📖 DTO

DTO(Data Transfer Object, 데이터 전송 객체)란 프로세스 간에 데이터를 전달하는 객체

🎈 회원 등록 API

1) Entity를 Request Body에 직접 매핑

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;

    @PostMapping("/api/v1/members")
    public CreateMemberResponse saveMemberV1(@RequestBody @Valid Member member) {
        Long id = memberService.join(member);
        return new CreateMemberResponse(id);
    }

    @Data
    static class CreateMemberResponse {
        private Long id;

        public CreateMemberResponse(Long id) {
            this.id = id;
        }
    }
}

◽ 실무에서는 회원 Entity를 위한 API가 다양하게 만들어지는데, 한 Entity에 각각의 API를 위한 모든 요청 요구사항을 담기는 어렵다
◽ Entity가 변경되면 API 스펙이 변한다
-> API 요청 스펙에 맞추어 별도의 DTO를 파라미터로 받는다

2) Entity 대신에 DTO를 RequestBody에 매핑

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;

    @PostMapping("/api/v2/members")
    public CreateMemberResponse saveMemberV2(@RequestBody @Valid CreateMemberRequest request) {
        Member member = new Member();
        member.setName(request.name);
        Long id = memberService.join(member);
        return new CreateMemberResponse(id);
    }

    @Data
    static class CreateMemberRequest {
        @NotEmpty
        private String name;
    }

    @Data
    static class CreateMemberResponse {
        private Long id;

        public CreateMemberResponse(Long id) {
            this.id = id;
        }
    }
}

◽ 요청 값으로 Member 엔티티 대신에 별도의 DTO를 받는다
◽ CreateMemberRequest를 Member Entity 대신에 RequestBody와 매핑한다
◽ Entity가 변해도 API 스펙이 변하지 않는다

📔 JSON

◽ JSON(JavaScript Object Notation)은 데이터를 저장/전송 할 때 많이 사용되는 형식
◽ 서버와 클라이언트 간의 통신에서 주로 많이 사용됨
◽ 간단한 형식을 갖는 문자열(데이터 교환에 주로 사용)
◽ Key, Value 구조를 가짐
◽ 문자열, 숫자, 배열, 불리언 그리고 다른 객체를 포함할 수 있음

📖 JSON 구조

1) JSON 데이터는 이름과 값의 쌍, key : value 형식으로 구성, 중괄호({})로 둘러쌓아 표현

{ key : value }
ex) {"name": "식빵"}

2) JSON 데이터는 쉼표(,)로 나열

{
	"name": "식빵",
    "family": "웰시코기",
    "age": 1,
    "weight": 2.14
}

📖 JSON 데이터 타입(datatype)

1) 숫자(number)
◽ 숫자는 정수 또는 부동소수여야 함. 큰 따옴표("")로 안 묶음

{ "year" : 2024 }

2) 문자열(string)
◽ 큰따옴표("")로 묶어준다

{ "name" : "kaeun" }

3) 불리언(boolean)
◽ 참 : true, 거짓 : false

{ "manager" : true }

4) 객체(object)
◽ 객체는 JSON 객체와 같은 규칙을 따라야 함

{ "code" : {
	"HTML":"기본틀",
    "CSS":"디자인",
    "JS":"동작가능"
    }
}

5) 배열(array)
◽ 배열(array)은 대괄호([])로 둘러쌓아 표현. 또한, JSON 배열은 쉼표(,)를 사용하여 여러 JSON 데이터를 포함할 수 있다

{ "number" : ["일", "이", "삼"] }

6) null
◽ null : 공간만 있을 뿐, 아무것도 없는 상태, 0과는 다른 개념

{ "point" : null }

7) JSON Array
◽ 여러개의 JSON Object들이 모인 것이 JSON Array로 대괄호로 둘러싸인 부분

[{"id": 0, "name": "식빵"}, //0번 index
{"id": 1, "name": "단팥빵"}, //1번 index
{"id": 2, "name": "소라빵"}] //2번 index

📚 참고자료

📖 실전! 스프링 부트와 JPA 활용2 - API 개발과 성능 최적화
📖 HTTP 메서드 종류 & 요청 흐름 💯 총정리
📖 REST API 구성/특징 총 정리
📖 RESTful API 이란
📖 JSON이란? - JSON 구조, JSON 데이터 타입, JSON Array