Rest API 정의

---

Rest API 정의

최근 서비스는 예전처럼 단순히 하나의 브라우저만 지원하는것과 다르게 여러 환경에서 실행되야하는 시대로 넘어왔다. 브라우저, 모바일 등의 통신에 대응해야하기 때문에 서버를 유연하고 범용성이 보장되는 디자인이 필요하여 2000년에 Roy Fielding에 의해 처음 용어가 사용되었다고 한다.

규칙

- URI는 정보의 자원을 표현해야 한다.

  GET /users/1

위의 URI에서 users는 Collection(=복수 리소스)이고 1은 Element(=단수 리소스)로 나누어 표현이 가능하다.

- 자원에 대한 행위는 HTTP Method(GET POST, PUT, DELETE 등)으로 표현한다.

- Content-Type header에 따라 해당하는 데이터를 response 한다.

  // users/1.xml보다 Content-Type Header를 포함하여 요청을 보내는것이 더 유연하다.
  GET /users/1

  1) Content-Type: application/json
  2) Content-Type: application/xml
  3) Content-Type: application/png
...

- Version

  // 버전을 활용하여 클라이언트측에서 구분하여 요청이 가능하게 한다. ( 새로운 버전 배포시에 기존버전또한 유지되므로 클라이언트에서 해당 버전정보만 변경해주면 된다. -> 즉, 기존 통신에 대한 오류 발생확률 감소 )
  GET /v1/users/1
  GET /v2/users/2

- HTTP Methods

URI	GET	PUT	POST	DELETE
http://localhost:8080/v1/users/	유저들의 목록을 가져옴	유저를 업데이트	유저 컬렉션에 속하는 새로운 자원을 생성	전체 유저 삭제
http://localhost:8080/v1/users/23	유저의 상세 정보를 가져옴	유저의 정보를 수정	유저의 자식 자원을 생성	해당 유저(=23) 삭제

이 외에 PATCH라는 HTTP Method가 있는데 PUT이 해당 자원의 전체를 수정하는 의미를 지니는 것과 다르게 PATCH는 일부를 변경한다는 의미를 지니므로 최근에는 Update에서 PUT보다 PATCH를 사용한다.

URI

• URI 뒤에 붙는 쿼리란?
  • 보편적으로 GET요청을 할 때에는 쿼리 스트링(?,=,&)기호를 사용하여 전달하며 REST API에서는 주로 페이징 값 혹은 검색 조건에 대한 값을 전달할 때 사용한다.

        GET /users?page=1&limit=10  // 페이징 정보 전달
        GET /users?age=23&name=전봉근   // 검색 조건 전달
    

  • 위와는 좀 다른 예시이다. 필요한 부분에 대한 인터페이스를 적절히 제공하기위하여 사용하는 예시(linkedIn, Facebook, Google등의 기업에서 사용한다.)

        GET /user:(id, name)    // 괄호안에 필요한 필드를 요청
        GET /bkjeon/friends?fields=id,name,age  // "bkjeon"인 사람의 친구들의 정보를 id,name,age 필드값만 제한하여 정보를 가져온다.
    

• URI 는 주로 소문자로 쓰는 것을 권장한다.

요청 헤더

• Accept

    GET /users HTTP/1.1
    Host: http://localhost:8080
    Accept:application/json,*/*;
  

• Accept-Charset

    // 응답받고 싶은 캐릭터셋을 명시
    Accept-Charset: iso-8859-5
  

• User-Agent

    // 요청을 보낸 User Agent의 정보를 표시하기 위해 사용
    User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0
  

응답 헤더

• Content-Length

    // 응답 메세지의 entity body의 크기를 표시
    Content-Length: 325
  

• Last-Modified

    // 해당 리소스가 갱신된 시간을 표시(캐싱 정책 관련)
    Last-Modified: Tue, 13 Nov 1994 13:35:25 GMT
  

HTTP Status Code

Status Code	Message	Description
200	OK	성공(만약 코드가 200인데 에러메세지를 포함하는 경우는 4XX대 코드를 사용하자.)
201	Created	리소스 생성 성공(CRUD 요청에서 Create이다.)
202	Accepted	비동기 요청에 대한 응답(모니터링할 수 있는 리소스 페이지를 안내하거나 처리되기까지의 예상 경과시간을 안내하는것이 일반적이다.)
400	Bad Request	일반적인 요청실패(서버가 이해할 수 없는 형식의 요청일 경우)
401	Unauthorized	권한이 없는 리소스에 접근하려 할 때(미 인증))
403	Forbidden	권한이 없는 리소스에 접근하려 할 때(위의 401코드와는 다르게 해당 코드는 인증여부와 관계없다.)
404	Not Found	URI와 매칭되는 리소스를 찾을 수 없을 때
405	Method Not Allowed	지원하지 않는 메소드(ex: GET, POST ...)일 경우
406	Not Acceptable	요청 Accept 헤더에 명시된 타입이 아닐경우
409	Conflict	클라이언트의 요청 형식에는 문제가 없지만 리소스 상태에 의해서 요청 자체를 수행할 수 없을 경우 -> 이미 삭제된 리소스를 또 삭제하거나, 비어있는 리소스에서 무언가를 요청할 경우
500	Internal Server Error	서버측 에러에 대한 응답 코드
503	Service Unavailable	가장 치명적인 코드이며 서버에 문제가 있다거나 유지보수에 의하여 잠시 접근이 거부 될 때 사용