3월 06, 2022

REST API

 REST란?

REpresentational

State

Transfer

  • Communication에 관한 것
  • RESTFUL : Communicate하기 위해 REST API를 쓰는 서비스

REST API의 장점들 

  1. Simple, Standardized
  2. Scalabel, Stateless
    1. 서비스가 복잡도가 커질때, 쉽게 수정을 가할 수 있음
    2. stateless하기에 데이터가 어떤 상태인지 걱정할 필요 없고, 그것들을 추적할 필요 없음
  3. Caching을 지원하기에, 높은 Performance를 보임
    1. 서버는 Response cache-control 헤더에 해당 요청이 캐싱이 가능한 지 여부를 제공한다. 이를 제공하면, 클라이언트는 Response를 캐싱하여 서버와 클라이언트 간의 상호작용을 줄이고, 성능과 서버의 가용성을 높인다.

재고가 있는 아이스크림의 맛 종류들을 보여주고, 직원들이 그 맛을 업데이트 할 수 있는 웹 어플리케이션을 만들려고 함

cloud based server와 REST API를 통해 통신



END POINT는 HTTP://Icecream.com/API/FLAVORS 같이 생겼을 것

“FLAVORS” = Resource

REST API를 통해 Request와 Response를 주고받는데, 

이때 REST API를 통해 할 것은? ⇒ CRUD

REST API에서 이 CRUD의 동의어는 HTTP “method” 또는 “operations”임


CREATE 는 POST

READ는 GET

UPDATE는 PUT

DELETE는 DELETE


REQUEST의 구성 
  • operation(HTTP methods)가 있고 ,
  • Endpoint
  • Parameter 혹은 Body가 있고
  • Headers가 있음: API Key 또는 인증 데이터 등을 담음
RESPONSE의 구성
  • JSON데이터의 형식 

어플리케이션에서 현재의 재고를 표시하고 싶다면?
  1. GET FLAVORS
    1. GET이 OPERATION(메소드)
    2. ENDPOINT는 /FLAVORS
    3. RESPONSE에는 맛에 대한 JSON데이터가 들어옴

맛을 바꿔주고 싶다면??

2.UPDATE(or Replace) FLAVORS
    1. PUT OPERATION
    2. ENDPOINT는 “/API/FLAVORS/1” : ID 1을 명시하여 지우고 싶은맛을 표시
    3. BODY(PARAMETER)에는 추가하고 싶은 맛을 적어줌

새로운 맛이 들어왔다면?

3. CREATE
  1. POST 오프레이션
  2. END POINT 는 “/FLAVORS”
  3. BODY에 만들고 싶은 맛을 넣음

REST API RESOURCE NAMING GUIDE 

What is Resource?

REST에서의 기본 데이터 표현이 Resource.

이름붙일 수 있는 한 어떠한 정보도 Resource가 될 수 있음 (문서, 이미지, 일시적 서비스 등등)

싱글톤과 컬렉션 리소스

customers : 컬렉션 리소스 “/customers” URI를 통해 컬렉션 리소스를 식별.

customer : singleton 리소스 “/customers/{customerID}” URI를 통해 개별 customer 리소스 식별 가능

  • 리소스에는 하위 컬렉션 리소스도 포함 가능
    • “/customers/{customerId}/accounts” 특정 customer의 sub-collection 리소스인 accounts를 해당 URN으로 식별.
    • 이 accounts의 singleton리소스인 “account”도 “/customers/{customerId}/accounts/{accountId}” 이렇게 식별됨

URI

  • Uniform : 리스소를 식별하는 통일된 방식
  • Resource : 자원.
  • Identifier

REST API는 URI를 통하여 리소스를 처리함.

REST API 디자이너는 REST API의 리소스 모델을 클라이언트에 전달하는 URI를 만들어야 함

리소스의 이름을 잘 지정하면 API가 직관적이고 사용이 용이함

URI 생성 규칙들

  1. 명사를 사용하여 자원을 나타냄

    리소스의 원형(아키타입)은 4가지로 나누어짐.

    1. document

      document 리소스는 단일개념.(object의 instance, db의 row)

      REST에서 이는 컬렉션 리소스 안의 싱글 리소스.

      resouce archetype을 나타내기 위하여 “단수”를 사용함

    2. collection

      서버가 관리하는 리소스 디렉토리

      “복수”를 사용

      POST기반 등록

    3. Store

      클라이언트가 관리하는 리소스 repository

      store 리소스는 클라이언트가 URI를 관리

      복수 사용

    4. Controller

      “동사” 사용

      실행가능한 기능 같은 것.


  2. 일관성이 제일 중요하다.

    : 일관성 있는 리소스 네이밍과 URI형식을 사용하여, 모호성을 최소화하고 가독성과 유지 보수 가능성을 최대화

    1. 계층 관계 표현을 위해 “/” (슬래쉬)를 사용

      http://api.example.com/device-management

      http://api.example.com/device-management/managed-devices

      http://api.example.com/device-management/managed-devices/{id}

      http://api.example.com/device-management/managed-devices/{id}/scripts

    2. URI의 마지막 값에 슬래쉬를 사용하지 않음

    3. - (하이픈)을 사용하여 URI 가독성 향상

    4. 긴 경로에서 - 사용하여 이름의 가독성을 향상시킴
      http://api.example.com/device-management/managed-devices
      가
      http://api.example.com/device-management/managedDevices
      보다 낫다

    5. 언더바를 사용하지 않는다

      1. 일부 브라우저나 화면에서 _ (언더바)가 가려지거나 숨겨질 수 있음 : 밑줄 대신 하이픈 사용

    6. URI에 소문자를 사용해라

    7. 파일 확장자를 사용하지 말라

      http://api.example.com/device-management/managed-devices.xml /이렇게 쓰면 안됨!

    8. URI에 CRUD 함수 이름을 사용하지 말라

      URI는 리소스를 식별하는데만 사용하고, 리소스에 대한 조치는 포함하면 안된다.

      리소스에 대한 작업은 HTTP 메소드를 사용해서 하기

    9. URI 컬렉션 필터링을 위하여 query component를 사용하라

      정렬, 혹은 필터된 리소스를 위하여 신규 API를 생성하지 않고 쿼리 파라미터를 활용

      http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date




참고자료
https://www.youtube.com/watch?v=lsMQRaeKNDk
https://restfulapi.net/resource-naming/

피드 구독하기: 댓글 (Atom)