Spring/SpringBoot

[ 항해 3주차 개인 과제 ] API 명세서 및 Q&A

따갓 2022. 7. 25. 16:08

1. 요구 사항

2. API 명세서

  Method URL  Request Response
모든 게시글 조회 GET /api/boards   {
"success": true,
"data": [
{
"createdAt":"2022-07-27T14:48:42.903424",
"modifiedAt": "2022-07-27T14:48:42.903424",
"id": 15,
"title": "제목3",
"author": "작성자3",
"content": "내용3"
},
{
"createdAt": "2022-07-27T14:48:35.625981",
"modifiedAt": "2022-07-27T14:48:35.625981",
"id": 14,
"title": "제목2",
"author": "작성자2",
"content": "내용2"
},
],
"error": null
}
단일 게시글 조회 GET /api/boards/{id}   {
"success": true,
"data": {
"createdAt":"2022-07-27T14:48:42.903424",
"modifiedAt": "2022-07-27T14:48:42.903424",
"id": 15,
"title": "제목3",
"author": "작성자3",
"content": "내용3"
},
"error": null
}
게시글 작성 POST /api/boards   {
"success": true,
"data": {
"createdAt":"2022-07-27T14:48:42.903424",
"modifiedAt": "2022-07-27T14:48:42.903424",
"id": 15,
"title": "제목3",
"author": "작성자3",
"content": "내용3"
},
"error": null
}
비밀번호 확인 POST /api/boards/{id}   {
"success": true,
"data": true,
"error": null
}
게시글 수정 PUT /api/boards/{id}   {
"success": true,
"data": {
"createdAt":"2022-07-27T14:48:42.903424",
"modifiedAt": "2022-07-27T14:48:42.903424",
"id": 15,
"title": "제목3수정",
"author": "작성자3수정",
"content": "내용3"
},
"error": null
}
게시글 삭제 DELETE /api/boards/{id}   {
"success": true,
"data": true,
"error": null
}

 

3. Q&A

Q1. 수정, 삭제 API의 request를 어떤 방식으로 사용하셨나요? (param, query, body)

  • 단일 게시글 조회, 비밀번호 확인, 게시글 수정, 게시글 삭제에 req.param 방식 사용.
  • 게시글 작성, 비밀번호 확인, 게시글 수정에 req.body 방식 사용

 

더보기

1. req.param

  • 주소에 포함된 변수를 담는다
  • 예를 들어 http://15.164.234.179/api/boards/123 라는 주소가 있다면 이는 123 을 담아서 보냈다는 뜻이다.
  • 서버에서 Path Variable 로 칭한다.

2.req.query

  • 주소 바깥의 '?' 이후의 변수를 담는다.
  • 예를 들어 http://15.164.234.179/api/boards?id=123&password=123456 이런 식으로 데이터를 두 개 담아서 넘길 수 있다.
  • 서버에서 Query parameter로 칭한다.

3.req.body

  • XML, JSON 등의 데이터를 담는다. 주소에서는 확인할 수 없다.
  • ARC 와 같은 도구로 내용을 확인할 수는 있다. 민감한 데이터의 경우 반드시 암호화해 전송해야 한다

[ param vs query ]

  • resource를 식별해야 하는 상황에서는 Path Variable 이 더 적합하다.
  • 정렬이나 필터링을 해야하는 상황에서는 Query Parameter이 더 적합하다.

[ query string( query / parameter ) vs body ]

1. body를 사용할 때

  • 매우 많은 수의 인수가 있을 때 >> 일부 웹 서버에는 URL 길이에 제한이 있다. 하지만 body에는 제한이 없다.

2. query string을 사용할 때

  • 코드를 개발하는 동안 수동으로 호출할 수 있기를 원할 때
  • 여러 웹 서비스에서 인수가 공통적인 경우

 

Q2. 어떤 상황에 어떤 방식의 request를 써야 하나요?

 

1. GET

리소스를 검색하고, 반환받기 위해 사용되는 메소드이다.
원하는 정보를 서버에 요청할 때 쓰인다.


2. POST

요청된 자원을 생성하기 위해 사용되는 메소드이다.
POST로 정보를 전송하면 URL에 파라미터가 나타나지 않으므로 각종 데이터를 전송하는데 쓰인다.


3. PUT

요청된 자원을 수정하기 위해 사용되는 메소드이다.


4. PATCH

요청된 자원을 수정하기 위해 사용되는 메소드라는 점에서 PUT과 같지만,
해당 자원 전체를 수정하는 PUT과는 다르게 PATCH는 해당 자원의 일부 부분을 수정한다.


5. DELETE

요청한 자원을 삭제하기 위해 사용되는 메소드이다.
클라이언트에서 서버의 자원을 삭제할 수 있도록 허가하는 것은 매우 위험하다.
그러므로 현실적으로는 사용될 일이 거의 없고, 대부분의 서버는 이 메소드를 비활성화 시킨다.

Q3. RESTful한 API를 설계했나요? 어떤 부분이 그런가요?

1. 자원( Resource ) 을 적절하게 보냈다.

  • " /api/boards/id " 와 같이 HTTP URI를 이용해 자원을 구별하여 요청하였다.
  • "boards" 와 같이 복수형으로 지정해주었다.

 

2. GET, POST, PUT, DELETE 와 같은 메서드를 적절하게 사용하였다.

  • 게시글 조회, 단일 게시글 조회에 GET 사용
  • 게시글 작성에 POST 사용
  • 게시글 수정에 PUT 사용
  • 게시글 삭제에 DELETE 사용

 

3. 적절한 형태의 자원을 사용하였다.

  • REST에서는 자원을 JSON, XML 등의 여러 형태로 나타내어 질 수 있다.
  • 이번 과제에서는 클라이언트와 서버간에 JSON 형태로 데이터를 주고 받게 하였다.

 

Q4. 적절한 관심사 분리를 적용하였나요? ( Controller , Service, Repository )

Controller , Service, Repository 의 역할에 맞게 코드를 잘 분리하였다고 생각한다!

  • BoardController : Controller에서 사용자의 요청이 어떤 것인지 확인하고, Service에게 요청에 맞는 작업을 진행하도록 코드를 작성.
  • BoardService : Service에서 Controller에서 전달받은 사용자의 요청사항에 알맞게 데이터를 가공해서 데이터베이스로 전달하거나, 데이터베이스에서 데이터를 전달받아 가공하여 유저에게 전달하게끔 코드를 작성.
  • BoardRepository : Repository 에서는 JPA를 사용하여 DB를 관리하였다.

 

더보기

 

[ 참고 ] Controller, Service, Repository

Controller

  • 사용자의 요청을 처리한 후 지정된 뷰에 모델객체를 넘겨주는 역할
  • 애플리케이션 로직 및 사용자의 입력 데이터를 서비스에 전달하고 처리하는 역할
  • 뷰를 연결하여 웹상에 띄우고 웹에서 가져오는 데이터들을 어떻게 처리하는지 지정해 놓으면 그역할에 맞춰 사용자의 요청을 처리

Service

  • 컨트롤러와 리포지토리 사이의 미들웨어
  • Model이 테이터베이스에서 받아온 데이터를 전달받아 가공하는 역할
  • Controller에서 전달받은 사용자의 요청사항에 알맞게 데이터를 가공해서 데이터베이스로 전달하거나, 데이터베이스에서 데이터를 전달받아 가공하여 유저에게 전달하는 역할
  • DB 정보가 필요할 때는 Repository에게 요청

Repository

  • DB 관리(연결, 해제, 자원 관리)
  • DB에 CRUD의 명령을 실행하게 만드는 인터페이스
  • '저장소'라는 뜻을 가진 단어로 JPA에서 Repository 인터페이스를 생성 후, JpaRepository<Entity, 기본키 타입>을 상속받으면(extends하면) 기본적인 Create, Read, Update, Delete가 자동으로 생성됨

 

 

Q5. 작성한 코드에서 빈(Bean)을 모두 찾아보세요!

@RestController, @Service, @ Repository, @Component 어노테이션이 붙은 클래스들은 Spring Framework 에서 

자동으로 Bean 으로 등록해준다. 또한 @SpringbootApplication 어노테이션을 붙이면 위의 어노테이션을 따로 붙이지 않아도 자동으로 스캔하여 Bean으로 등록해준다. 

위 사진처럼 빈 클래스 아이콘을 통해서 쉽게 확인할 수 있다.

>> BoardController , BoardService , BoardRepository, RestApiExceptionHandler, Application 등...

 

 

Q6. API 명세서 작성 가이드라인을 검색하여 직접 작성한 명세서와 비교해보세요!

 

 

 

 

 

출처 : https://dar0m.tistory.com/222

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

[ SpringBoot ] JPA 간단 정리  (0) 2022.07.22
[ SpringBoot ] Gradle 사용하기  (0) 2022.07.22

'Spring/SpringBoot'의 다른글

  • 현재글[ 항해 3주차 개인 과제 ] API 명세서 및 Q&A

관련글

댓글

티스토리툴바