[HTTP] REST API 모범 사례 조사 및 발표 준비

[발표 주제] 다음 기능에 대한 REST API 모범 사례를 연구해서 제출하세요.
1. 조회 
 > 특정 블로그 글에 달린 댓글 조회
2. 기타 (어떤 메소드가 적합한지 고민해보세요!)
 > 블로그 글 좋아요
 > 블로그 글 좋아요 취소
 > 다른 글쓴이 팔로우

조회

1. 특정 블로그 글에 달린 댓글 조회

paths: # 메서드
  /comment: # 댓글 관련 메서드
    get: # 모든 댓글 조회 - 특정 글의 모든 댓글
      description: '모든 댓글 조회 - 특정 글의 모든 댓글'
      responses:
        '200':
          description: "성공 응답"
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
        '404':
          description: "페이지가 존재하지 않음"

GET /articles/{articleId}/comments
GET /comments?articleId={articleId}

기타

components: # 데이터 모델
  schemas:
    Article: # 게시글
      type: object
      required:
        - article_seq
        - title
        - content
        - user_id
      properties:
        article_seq:
          type: number
          example: '1'
        title:
          type: string
          example: '3월 15일의 TIL'
        content:
          type: string
          example: '오늘은 REST API를 배웠다!'
        user_id:
          type: string
          example: 'kimcoding'
        reg_date:
          type: string
          format: date-time
          example: '2023-03-23 00:00:00'
        mod_user_id:
          type: string
          example: 'kimcoding'
        mod_date:
          type: string
          format: date-time
          example: '2023-03-23 00:00:00'
    Comment: # 댓글
      type: object
      required:
        - comment_seq
        - article_seq
        - user_id
        - content
      properties:
        comment_seq:
          type: number
          example: '1'
        article_seq:
          type: number
          example: '1'
        user_id:
          type: string
          example: 'kimcoding'
        content:
          type: string
          example: '열심히 공부하셨군요. 잘 보고 갑니다.'
        reg_date:
          type: string
          format: date-time
          example: '2023-03-23 00:00:00'
        mod_user_id:
          type: string
          example: 'kimcoding'
        mod_date:
          type: string
          format: date-time
          example: '2023-03-23 00:00:00'
    Subscription: # 구독 관련 정보
      type: object
      required:
        - user_id
        - sub_user_id
      properties:
        user_id:
          type: string
          example: 'kimcoding'
        sub_user_id:
          type: string
          example: 'subcoding'

1. 블로그 글 좋아요 및 취소

 paths: # 메서드
  /article/{article_seq}:
    post: # 특정 블로그글에 좋아요 및 취소
      description: '특정 블로그글에 좋아요 및 취소'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/Article'
      responses:
        '200':
          description: '성공 응답'
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'             
        '404':
          description: '존재하지 않는 페이지'

POST /articles/{articleId}/like
Authorization: token value

DELETE /articles/{articleId}/like
Authorization: token value

2. 다른 글쓴이 팔로우

 paths: # 메서드
  /subscription/{user_id}:
    put: # 다른 사람 팔로우
      description: '다른 사람 팔로우'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/Subscription'
      responses:
        '200':
          description: '성공 응답'
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Subscription'             
        '404':
          description: '존재하지 않는 페이지'

댓글 조회 기능의 REST API 모범 사례:  HTTP Method: GET Endpoint: /blog-posts/{post_id}/comments 이 엔드포인트는 특정 블로그 글에 달린 모든 댓글을 조회합니다. 블로그 글 ID를 사용하여 요청을 수행합니다. HTTP 응답 코드: 200 OK: 성공적으로 댓글을 조회한 경우 404 Not Found: 해당 블로그 글이 없는 경우 401 Unauthorized: 인증되지 않은 사용자가 접근한 경우 블로그 글 좋아요 기능의 REST API 모범 사례: HTTP Method: POST Endpoint: /blog-posts/{post_id}/likes 이 엔드포인트는 특정 블로그 글에 좋아요를 추가합니다. 블로그 글 ID를 사용하여 요청을 수행합니다. 이 엔드포인트는 또한 중복 좋아요를 방지하기 위해 이미 좋아요를 한 경우도 처리합니다. HTTP 응답 코드: 201 Created: 좋아요가 추가된 경우 404 Not Found: 해당 블로그 글이 없는 경우 401 Unauthorized: 인증되지 않은 사용자가 접근한 경우 409 Conflict: 이미 좋아요를 한 경우 블로그 글 좋아요 취소 기능의 REST API 모범 사례: HTTP Method: DELETE Endpoint: /blog-posts/{post_id}/likes/{like_id} 이 엔드포인트는 특정 블로그 글에서 좋아요를 취소합니다. 블로그 글 ID와 좋아요 ID를 사용하여 요청을 수행합니다. 이 엔드포인트는 좋아요가 없는 경우도 처리합니다. HTTP 응답 코드: 204 No Content: 좋아요가 성공적으로 취소된 경우 404 Not Found: 해당 블로그 글 또는 좋아요가 없는 경우 401 Unauthorized: 인증되지 않은 사용자가 접근한 경우 다른 글쓴이 팔로우 기능의 REST API 모범 사례: HTTP Method: POST Endpoint: /users/{user_id}/follow 이 엔드포인트는 다른 사용자를 팔로우합니다. 사용자 ID를 사용하여 요청을 수행합니다. 이 엔드포인트는 이미 팔로우한 경우도 처리합니다. HTTP 응답 코드:201 Created: 사용자가 성공적으로 팔로우된 경우 404 Not Found: 해당 사용자가 없는 경우 401 Unauthorized: 인증되지 않은 사용자가 접근한 경우 409 Conflict: 이미 팔로우한 경우

 

Reference

• OpenAPI Specification
• swagger petstore
• RESTful API Designing guidelines — The best practices
• 5가지의 기본적인 REST API 디자인 가이드
• 호주 정부 API 작성 가이드
• 구글 API 작성 가이드
• MS의 REST API 가이드라인