목차
REST API 란?
다시한번 짚고가기
API 가 시장에 도입되었을 당시 어떤식으로 설계/명명/구조 해야하는지 규약/규격이 존재하지 않았습니다. 이로인해 프론트엔드, 백엔드 모두 많은 시간을 API 개발 문서를 이해하는 데 사용했죠. 이를 효율적으로 해결하기 위해 나온것이 REST API 입니다.
RESTful API 설계란?
자원(리소스) 지향
•
API는 명사를 사용하여 리소스를 기반으로 설계되어야 합니다.
•
예 /users, /products
HTTP 메서드 사용
•
GET : 리소스 조회
•
POST : 리소스 생성
•
PUT : 리소스 전체 수정
•
PATCH : 리소스 부분 수정
•
DELETE : 리소스 삭제
상태 코드 사용
•
적절한 HTTP 상태 코드를 사용하여 요청의 결과를 나타냅니다.
•
예 200 OK, 404 Not Found, 500 Internal Server Error
데이터 형식
일반적으로 JSON을 사용하여 데이터를 교환합니다.
HATEOAS
응답에 다음 액션 또는 관련 리소스에 대한 링크를 포함하여 애플리케이션 상태의 동적 변경을 가능하게 합니다.
RESTful API 개발 시 고려해야 하는 것
Stateless
•
세션 등 클라이언트와 서버가 서로의 상태를 저장하지 않아야 합니다.
•
Token (JWT) 을 사용합니다.
균일한 인터페이스
데이터베이스 정규화 (Database normalization)
•
엔티티간 반복적인 연결을 피하고 중복된 원형 연결(Circular Reference)을 만들지 않는다.
•
순환참조 확인
# 예시 1
학생 > 교수 > 학생 X
교수 > 학생 > 교수 X
# 예시 2
학생 > 교수 > 코스 > 학생 X
교수 > 학생 > 교수 X
# 예시 3
학생 > 순환 끝
교수 > 순환 끝
코스 > 교수 > 순환 끝
코스 > 학생 > 순환 끝
- 모든 케이스에서 순환 발견 X
Markdown
복사
•
새로운 필드가 추가될 때 기존 테이블을 변경하지 않고 새로운 종속성을 가져야 합니다.
•
엔티티는 자신과 관련된 데이터만을 포함하고, 다른 종속 엔티티와 관련된 데이터는 포함하지 않습니다.
HTTP Request 구성요소 설계
HTTP Request 의 요소 | |
HTTP 메서드 (HTTP Method) | Method |
GET / POST / PUT / PATCH / DELETE | |
URI (Uniform Resource Identifier) | URI URI 개념 보러가기 |
URL URL 개념 보러가기 | |
HTTP 버전 (HTTP Version) | 통신 HTTP 버젼 |
헤더 (Headers) | Token 종류 및 값 |
본문 (Body) | 데이터 |
실습
사용자(User)
1. 사용자를 생성한다.
2. 사용자의 세부 정보를 볼 수 있습니다.
3. 사용자 목록을 볼 수 있습니다.
4. 사용자를 편집할 수 있습니다.
5. 사용자를 삭제할 수 있습니다.
6. 사용자가 보유한 작업 목록을 볼 수 있습니다.
작업(Task)
1. 작업을 생성할 수 있습니다.
2. 작업의 세부 정보를 볼 수 있습니다.
3. 작업 목록을 볼 수 있습니다.
4. 작업을 편집할 수 있습니다.
5. 작업을 제거할 수 있습니다.
6. 작업에 할당 된 사용자를 볼 수 있습니다.
더해서,
7. 작업에 특정 사용자를 할당할 수 있습니다.
8. 작업에서 특정 사용자 할당을 해제할 수 있습니다.
Markdown
복사
1. POST /api/users
2. GET /api/users/{id}
3. GET /api/users
4. PUT /api/users/{id}
5. DELETE /api/users/{id}
6. GET /api/users/{id}/tasks
7. POST /api/tasks/{id}/users/{id}
8. DELETE /api/tasks/{id}/users/{id}
7. POST /api/users/{id}/tasks/{id}
8. DELETE /api/users/{id}/tasks/{id}
Markdown
복사
자원 이외 URL 에 작명
작명 | 사용도 | 용도 |
api | 상 | API 와 웹사이트를 구분짓기 위해 사용합니다. |
도메인 | 상 | 마이크로 서비스별 url 분리위해 사용합니다. |
json, xml | 리턴 타입을 보여주기 위해 사용합니다. | |
v1 | API 버저닝에 사용합니다. 여러 서비스에 API 를 제공중일 때 사용합니다. | |
open, docs | API 종류 및 권한여부를 알려주기 위해 사용합니다. |
HTTP Response 구성요소 설계
HTTP Response 의 요소 | |
상태 라인 (Status Line) | HTTP 버전, 상태 코드, 및 상태 메시지로 구성됩니다. "HTTP/1.1 200 OK” (DELETE 성공 시 204) |
헤더 (Headers) | Response 부가 정보를 반환합니다. |
Content-type | |
본문 (Body) | 데이터 |
•
Content-type
text/plain | 평문 | application/pdf | PDF |
text/html | HTML 문서 | image/jpeg | JPEG 이미지 |
application/json | JSON | audio/mpeg | MP3 오디오 |
application/xml | XML | video/mp4 | MP4 비디오 |