REST API 정리

개발할때 마다 매번 다르게 생각해서 구성하는데 지금생각을 문서로 정리해놓고 api을 제공할때 최상의 방법을 생각해보자.

 

POST : 리소스를 생성(Create)
GET : 리소스의 정보를 조회(Read)
PUT : 리소스를 수정(Update)
DELETE : 리소스를 삭제(Delete)

 

 

POST : 인증 (Authentication & Authorization)

- OAuth2.0 및 JWT 인증 (조금 틀리지만 아래로 퉁치자)

 

- REQUEST
  curl -X POST \
    'https://test.api.com/api/v1/oauth/token' \
    -H 'Authorization: Basic {base64_encode({client_id}:{client_secret})}' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}'

- RESPONSE
  HTTP/1.1 200 OK
  {
      "access_token": "..........",
      "expires_at": "2022-...",
      "refresh_token": "..........",
      "refresh_token_expires_at": "2022-...",
      "scopes": [
          "test.read_user"
          ...
      ]
  }

- REQUEST
  curl -X POST \
    'https://test.api.com/api/v1/oauth/token' \
    -H 'Authorization: Basic {base64_encode({client_id}:{client_secret})}' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=refresh_token&refresh_token={refresh_token}'

- RESPONSE
  HTTP/1.1 200 OK
  {
    "access_token": "..........",
    "expires_at": "2022-...",
    "refresh_token": "............",
    "refresh_token_expires_at": "2022",
    "scopes": [
        "test.read_user"
        ...
    ]
    ...
  }

 

POST : 등록 (Create)

- REQUEST
  curl -X POST \
    'http://test.api.com/api/v1/users' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "request": {
          "id": "kang1",
          "name": "강덕준1",
          ...
      }
    }'

- RESPONSE
  HTTP/1.1 200 OK
  ...
  "user": [
    {
        "user_no": 1,
        "user_name": "강덕준1",
        "id": "kang1"
        ...
    }
  ]

 

 

GET : 조회(Read)

- REQUEST
  curl -X GET \
    'https://test.api.com/api/v1/users' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json'

- RESPONSE
  HTTP/1.1 200 OK
  ...
  "users": [
    {
        "user_no": 1,
        "user_name": "강덕준1",
        "id": "kang1",
        "roles": [
          'ROLE_USER',
          'ROLE_MANAGER'
        ]
    },
    {
        "user_no": 2,
        "user_name": "강덕준2",
        "id": "kang2",
        "roles": [
          'ROLE_USER'
        ]
    },
    ...
  ]


- REQUEST
  curl -X GET \
    'https://test.api.com/api/v1/users/{user_no}' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json'

- RESPONSE
  HTTP/1.1 200 OK
  ...
  "user": {
      "user_no": 1,
      "user_name": "강덕준1",
      "id": "kang1",
      "roles": [
        'ROLE_USER',
        'ROLE_MANAGER'
      ]
  }


- REQUEST
  curl -X GET \
    'https://test.api.com/api/v1/users/{user_no}/roles' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json'

- RESPONSE
  HTTP/1.1 200 OK
  ...
  "roles": [
    'ROLE_USER',
    'ROLE_MANAGER'
  ]


- REQUEST
  curl -X GET \
    'https://test.api.com/api/v1/users/count' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json'

- RESPONSE
  HTTP/1.1 200 OK
  {
    "count": 2
  }

 

PUT : 수정(Update)

- REQUEST
  curl -X PUT \
    'https://test.api.com/api/v1/users/{user_no}' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "request": {
        "id": "kang1",
        "name": "강덕준1-1",
        ...
      }
  }'

- RESPONSE
  HTTP/1.1 200 OK
  ...
  "user": {
      "user_no": 1,
      "user_name": "강덕준1-1",
      "id": "kang1"
      ...
  }

DELETE : 삭제(Delete)

- REQUEST
  curl -X DELETE \
    'https://test.api.com/api/v1/users/{user_no}' \
    -H 'Authorization: Bearer {access_token}' \
    -H 'Content-Type: application/json'
    
- RESPONSE
  HTTP/1.1 200 OK
  ...
  "user": {
      "user_no": 1
      ...
  }

 

Python Flask 에서 Swagger로 만든 샘플