1. API 식별하기

개발자 도구에서 fetch/XHR 항목을 본다.

request, response 헤더를 확인할 수 있다.
general에서 Request url과 request method, status code를 확인할 수 있다.
또한 밑의 response header와 request header에서 컨텐트 타입 등을 확인할 수 있었다.

2. 맛집 관리 API 명세서 작성하기

REST API 명세서이므로 RESTful하게 작성되어야한다.

📌  맛집 등록

Request - 요청

• Method: POST
• URL: /api/places
• Content-Type: application/json
• Body:

  {
  	"name" : "맛집3",
  	"address" : "주소-주소-3",
  	"call" : "111-2222-3336",
  	"category" : "양식",
  	"rating" : 5
  }

  새로이 정보를 등록하는, 서버에 정보를 전송하는 것이기에 method는 post이다.
  그래서 리퀘스트 바디에 등록할 맛집 정보를 json 형태로 담아 전송한다.

Response

• Status Code: 201 Created
• Body:

  {
  	"id" :3,
  	"name" : "맛집3",
  	"address" : "주소-주소-3",
  	"call" : "111-2222-3336",
  	"category" : "양식",
  	"rating" : 5
  }

응답에서는 성공적으로 전송되었을 경우 201 코드와 함께 새로이 등록된, id가 추가된 맛집정보 json 데이터를 body에 담아 반환해준다.

• Status Code: 400 Bad Request
• Body:

  //필수 필드를 누락하여 요청하였을 때
  {
  	"message" : "필수 필드가 누락되었습니다."
  }

• Status Code: 500
• Body:

  {
  	"message" : "서버에서 요청을 처리하는 도중에 문제가 발생하였습니다"
  }

  📌  전체 조회

  Request - 요청

  • Method: GET

  • URL: /api/places

  • Content-Type: application/json

    Response

  • Status Code: 200 OK

  • Body:

    //위와 같은 JSON 형태의 가게 정보들의 배열 리스트
    //없을 경우 빈 배열 리턴
    [
        {
            "id": 1,
            "name": "맛집1",
            "address": "주소-주소-1",
            "call": "111-2222-3333",
            "category": "한식",
            "rating": 5
        },
        {
            "id": 2,
            "name": "맛집2",
            "address": "주소-주소-2",
            "call": "111-2222-3334",
            "category": "한식",
            "rating": 4
        }
    ]

  • Status Code: 500

  • Body:

    {
    	"message" : "서버에서 요청을 처리하는 도중에 문제가 발생하였습니다"
    }

📌  맛집 삭제

Request - 요청

• Method: DELETE

• URL: /api/places/{id}

• Path Parameters:

  키	값
  id	1

• Content-Type: application/json

  Response
  

• Status Code: 204 No content

• Status Code: 404 Not found

• Body:

   //존재하지 않는 id에 접근하려고 하였을 
   {
   	"message" : "해당하는 id의 데이터를 찾을 수 없습니다."
   }

• Status Code: 500

• Body:

     {
     	"message" : "서버에서 요청을 처리하는 도중에 문제가 발생하였습니다"
     }

  성공적으로 요청이 왔을 경우, 204 body가 없는 No content 코드를 반환한다.
  오류의 경우 404, 500 각각의 코드와 함께 오류 메시지를 반환한다.

  직접적으로 API 명세서를 작성해보면서 API 명세서에는 어떤 정보가 필요한지, 그리고 처음 이 명세서를 보는 사람이 바로 어떤 API인지 파악할 수 있게 작성하려면 어떻게 해야하는지 고민하는 계기가 되었다.