개요

HTTP 동사

본 REST API에서 사용하는 HTTP 동사(verbs)는 가능한한 표준 HTTP와 REST 규약을 따릅니다.

동사 용례

GET

리소스를 가져올 때 사용

POST

새 리소스를 만들 때 사용

PUT

기존 리소스를 수정할 때 사용

PATCH

기존 리소스의 일부를 수정할 때 사용

DELETE

기존 리소스를 삭제할 떄 사용

HTTP 상태 코드

본 REST API에서 사용하는 HTTP 상태 코드는 가능한한 표준 HTTP와 REST 규약을 따릅니다.

상태 코드 용례

200 OK

요청을 성공적으로 처리함

201 Created

새 리소스를 성공적으로 생성함. 응답의 Location 헤더에 해당 리소스의 URI가 담겨있다.

204 No Content

기존 리소스를 성공적으로 수정함.

400 Bad Request

잘못된 요청을 보낸 경우. 응답 본문에 더 오류에 대한 정보가 담겨있다.

404 Not Found

요청한 리소스가 없음.

오류

에러 응답이 발생했을 때 (상태 코드 ⇒ 400), 본문에 해당 문제를 기술한 JSON 객체가 담겨있다. 에러 객체는 다음의 구조를 따른다.

Path Type Description

message

String

에러메세지

status

Number

에러상태

errors

Array

에러내용

errors[].field

String

에러필드

errors[].value

String

에러값

errors[].reason

String

에러이유

code

String

에러코드

예를 들어, 잘못된 요청으로 채용 공고를 만들려고 했을 때 다음과 같은 400 Bad Request 응답을 받는다.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 546

{
  "message" : " Invalid Input Value",
  "status" : 400,
  "errors" : [ {
    "field" : "companyId",
    "value" : "",
    "reason" : "must not be null"
  }, {
    "field" : "skill",
    "value" : "",
    "reason" : "must not be empty"
  }, {
    "field" : "reward",
    "value" : "",
    "reason" : "must not be null"
  }, {
    "field" : "position",
    "value" : "",
    "reason" : "must not be empty"
  }, {
    "field" : "description",
    "value" : "",
    "reason" : "must not be empty"
  } ],
  "code" : "C002"
}

하이퍼미디어

본 REST API는 하이퍼미디어와 사용하며 응답에 담겨있는 리소스는 다른 리소스에 대한 링크를 가지고 있다. 응답은 Hypertext Application from resource to resource. Language (HAL) 형식을 따른다. 링크는 `_links`라는 키로 제공한다. 본 API의 사용자(클라이언트)는 URI를 직접 생성하지 않아야 하며, 리소스에서 제공하는 링크를 사용해야 한다.

리소스

지원자

지원자 리소스는 채용 이력을 만들 때 사용한다.

지원이력 생성

POST 요청을 통해 새로운 채용공고의 지원이력을 만들 수 있다.

Example request

$ curl 'http://localhost:8080/api/applicants/1/application-histories' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "recruitmentId" : 0
}'

Path parameters

Table 1. /api/applicants/{applicant-id}/application-histories
Parameter Description

applicant-id

지원자의 id

HTTP request

POST /api/applicants/1/application-histories HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 27
Host: localhost:8080

{
  "recruitmentId" : 0
}

Request fields

Path Type Description

recruitmentId

Number

지원할 채용공고의 id

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/applicants/1/application-histories/1
Content-Type: application/hal+json
Content-Length: 321

{
  "applicationHistoryId" : 1,
  "recruitmentId" : 0,
  "applicantId" : 1,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/applicants/1/application-histories/1"
    },
    "profile" : {
      "href" : "/docs/index.html#resources-applicants-id-application-histories-create"
    }
  }
}

Response headers

Name Description

Location

생성된 지원이력의 id

Content-Type

Content-Type header

Response fields

Path Type Description

applicationHistoryId

Number

생성된 지원이력의 id

recruitmentId

Number

지원한 채용공고의 id

applicantId

Number

지원자의 id
Relation Description

self

Link to self

profile

Link to profile

채용

채용 리소스는 채용을 만들거나, 삭제 또는 조회할 때 사용한다.

채용 생성

POST 요청을 사용해서 새로운 채용을 만들 수 있다.

Example request

$ curl 'http://localhost:8080/api/recruitments' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "companyId" : 0,
  "position" : "백엔드 주니어 개발자",
  "reward" : 1000000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 채용합니다. 자격요건은..",
  "skill" : "Python"
}'

HTTP request

POST /api/recruitments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 227
Host: localhost:8080

{
  "companyId" : 0,
  "position" : "백엔드 주니어 개발자",
  "reward" : 1000000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 채용합니다. 자격요건은..",
  "skill" : "Python"
}

Request fields

Path Type Description

companyId

Number

회사 ID

position

String

채용포지션

reward

Number

채용보상금

description

String

채용내용

skill

String

사용기술

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/recruitments/3
Content-Type: application/hal+json
Content-Length: 795

{
  "id" : 3,
  "companyId" : 0,
  "position" : "백엔드 주니어 개발자",
  "reward" : 1000000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 채용합니다. 자격요건은..",
  "skill" : "Python",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/recruitments/3"
    },
    "delete" : {
      "href" : "http://localhost:8080/api/recruitments/3"
    },
    "update" : {
      "href" : "http://localhost:8080/api/recruitments/3"
    },
    "queryRecruitments" : {
      "href" : "http://localhost:8080/api/recruitments"
    },
    "queryRecruitment" : {
      "href" : "http://localhost:8080/api/recruitments/3"
    },
    "profile" : {
      "href" : "/docs/index.html#resources-recruitments-create"
    }
  }
}

Response headers

Name Description

Location

Location header

Content-Type

content type header

Response fields

Path Type Description

id

Number

채용공고 ID

companyId

Number

회사 ID

position

String

채용포지션

reward

Number

채용보상금

description

String

채용내용

skill

String

사용기술
Relation Description

self

Link to self

update

Link to update

delete

Link to delete

queryRecruitment

Link to query recruitment

queryRecruitments

Link to query recruitments

profile

Link to profile

채용 목록 조회

GET 요청을 사용하여 서비스의 모든 채용을 조회할 수 있다.

Example request

$ curl 'http://localhost:8080/api/recruitments' -i -X GET

Query parameters

Parameter Description

skill

사용기술

company

회사명

HTTP request

GET /api/recruitments HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1567

{
  "_embedded" : {
    "recruitmentsGetResponseDtoList" : [ {
      "id" : 7,
      "companyName" : "원티드랩",
      "nation" : "한국",
      "region" : "서울",
      "position" : "백엔드 주니어 개발자",
      "reward" : 1000000,
      "skill" : "Python",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/recruitments/7"
        },
        "update" : {
          "href" : "http://localhost:8080/api/recruitments/7"
        },
        "delete" : {
          "href" : "http://localhost:8080/api/recruitments/7"
        },
        "queryRecruitments" : {
          "href" : "http://localhost:8080/api/recruitments"
        }
      }
    }, {
      "id" : 8,
      "companyName" : "원티드랩",
      "nation" : "한국",
      "region" : "서울",
      "position" : "백엔드 주니어 개발자",
      "reward" : 1000000,
      "skill" : "Python",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/recruitments/8"
        },
        "update" : {
          "href" : "http://localhost:8080/api/recruitments/8"
        },
        "delete" : {
          "href" : "http://localhost:8080/api/recruitments/8"
        },
        "queryRecruitments" : {
          "href" : "http://localhost:8080/api/recruitments"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/recruitments"
    },
    "profile" : {
      "href" : "/docs/index.html#resources-recruitments-list"
    }
  }
}

Response fields

Path Type Description

_embedded.recruitmentsGetResponseDtoList[].id

Number

채용공고 ID

_embedded.recruitmentsGetResponseDtoList[].companyName

String

회사명

_embedded.recruitmentsGetResponseDtoList[].nation

String

국가

_embedded.recruitmentsGetResponseDtoList[].region

String

지역

_embedded.recruitmentsGetResponseDtoList[].position

String

채용포지션

_embedded.recruitmentsGetResponseDtoList[].reward

Number

채용보상금

_embedded.recruitmentsGetResponseDtoList[].skill

String

사용기술

_embedded.recruitmentsGetResponseDtoList[]._links

Object

Link to embedded resource
Relation Description

self

Link to self

profile

Link to profile

채용 조회

Get 요청을 사용해서 기존 채용 하나를 조회할 수 있다.

Example request

$ curl 'http://localhost:8080/api/recruitments/9' -i -X GET

Path parameters

Table 1. /api/recruitments/{id}
Parameter Description

id

채용공고 ID

HTTP request

GET /api/recruitments/9 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 976

{
  "id" : 9,
  "companyName" : "원티드랩",
  "nation" : "한국",
  "region" : "서울",
  "position" : "백엔드 주니어 개발자",
  "reward" : 1000000,
  "skill" : "Python",
  "description" : "원티드랩에서 백엔드 주니어 개발자를 채용합니다. 자격요건은..",
  "anotherRecruitments" : [ 10, 11 ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/recruitments/9"
    },
    "update" : {
      "href" : "http://localhost:8080/api/recruitments/9"
    },
    "delete" : {
      "href" : "http://localhost:8080/api/recruitments/9"
    },
    "queryRecruitments" : {
      "href" : "http://localhost:8080/api/recruitments"
    },
    "profile" : {
      "href" : "/docs/index.html#resources-recruitment-get"
    },
    "queryAnotherRecruitments" : [ {
      "href" : "http://localhost:8080/api/recruitments/10"
    }, {
      "href" : "http://localhost:8080/api/recruitments/11"
    } ]
  }
}

Response fields

Path Type Description

id

Number

채용공고 ID

companyName

String

회사명

nation

String

국가

region

String

지역

position

String

채용포지션

reward

Number

채용보상금

skill

String

사용기술

description

String

채용내용

anotherRecruitments

Array

회사의 다른 채용공고
Relation Description

self

Link to self

update

Link to update

delete

Link to delete

queryRecruitments

Link to query recruitments

profile

Link to profile

queryAnotherRecruitments

Link to query company’s another recruitments

채용 수정

PUT 요청을 사용해서 기존 채용을 수정할 수 있다.

Example request

$ curl 'http://localhost:8080/api/recruitments/4' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "position" : "백엔드 주니어 개발자",
  "reward" : 1500000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 '적극' 채용합니다. 자격요건은..",
  "skill" : "Python"
}'

Path parameters

Table 1. /api/recruitments/{id}
Parameter Description

id

채용공고 ID

HTTP request

PUT /api/recruitments/4 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 216
Host: localhost:8080

{
  "position" : "백엔드 주니어 개발자",
  "reward" : 1500000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 '적극' 채용합니다. 자격요건은..",
  "skill" : "Python"
}

Request fields

Path Type Description

position

String

채용포지션

reward

Number

채용보상금

description

String

채용내용

skill

String

사용기술

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 719

{
  "id" : 4,
  "companyId" : 3,
  "position" : "백엔드 주니어 개발자",
  "reward" : 1500000,
  "description" : "원티드랩에서 백엔드 주니어 개발자를 '적극' 채용합니다. 자격요건은..",
  "skill" : "Python",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/recruitments/4"
    },
    "delete" : {
      "href" : "http://localhost:8080/api/recruitments/4"
    },
    "queryRecruitments" : {
      "href" : "http://localhost:8080/api/recruitments"
    },
    "queryRecruitment" : {
      "href" : "http://localhost:8080/api/recruitments/4"
    },
    "profile" : {
      "href" : "/docs/index.html#resources-recruitments-update"
    }
  }
}

Response fields

Path Type Description

id

Number

채용공고 ID

companyId

Number

회사 ID

position

String

채용포지션

reward

Number

채용보상금

description

String

채용내용

skill

String

사용기술
Relation Description

self

Link to self

delete

Link to delete

queryRecruitment

Link to query recruitment

queryRecruitments

Link to query recruitments

profile

Link to profile

채용 삭제

DELETE 요청을 사용해서 채용을 삭제할 수 있다.

Example request

$ curl 'http://localhost:8080/api/recruitments/12' -i -X DELETE

Path parameters

Table 1. /api/recruitments/{id}
Parameter Description

id

채용공고 ID

HTTP request

DELETE /api/recruitments/12 HTTP/1.1
Host: localhost:8080