☕️ API 란? == 약속
API 란 쉽게 설명하면 클라이언트와 백엔드 간의 약속이라고 생각하면 좋다. 예를 들어서 카페에 가서 고객(클라이언트)이 '아메리카노 주세요!' 라고 하면 점원이 ☕️ 짜-안 하고 아메리카노를 만들어서(서버에서 처리) 고객에게 준다. 마찬가지로 클라이언트가 API 서버에게 'https://velog.io/@vonvoyage27/%ED%8F%AC%ED%8A%B8%ED%8F%B4%EB%A6%AC%EC%98%A4-4%EC%A3%BC-%EB%A7%8C%EC%97%90-%EC%A4%80%EB%B9%84%ED%95%98%EA%B8%B0%EB%84%A4%EB%B2%88%EC%A7%B8-API-%EC%84%A4%EA%B3%84%ED%95%98%EA%B8%B0' 이 주소로 요청하면('아메리카도 주세요!'와 같이) 지금 보이는 이 페이지에 필요한 정보를 반환해준다.('아메리카노'가 짜-잔하고 나오는 것과 같이)
😶 이제 그렇다면 REST API 디자인이 뭘까?
REST 라는 용어 또는 개념은 웹(HTTP) 논문의 주요 저자 중 한명인 로이 릴딩이 웹(HTTP) 설계의 우수성과 장점을 최대한 활용할 수 있는 아키텍처이다.
REST API 설계지 가장 중요한 것은 아래 2가지인데
첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
후.. URI는 정보의 자원을 표현한다는 말이 뭔말인지 좀 어려운데 아래에서 하나씩 차차 이해해보면 좋다. 언제나 샘플로 이해하는게 가장 쉽고 빠르다.
아래 방식은 REST를 제대로 적용하지 않은 URI 인데, delete와 같은 행위에 대한 표현이 들어가서는 안되고 자원 members 를 표현하는데 중점을 두어야한다.
올바른 예: /members/1
잘못된 예: /members/delete/14가지의 HTTP Method를 가지고 CRUD(POST, GET, PUT, DELETE)를 할 수 있다. 주의할 점은 URI에 '단수 명사' 와 '복수 명사'를 섞어서 사용하지 않고 '복수 명사' 만 사용한다.
올바른 예: /users/8, /items/5
잘못된 예: /user/8, /item/5
위의 예시에 보면 GET /items 같은 경우 상품 전체 목록 보기이고, GET /items/{id} 같은 경우 해당 ID 하나의 상품 정보 보기이다.
❗️ URI 설계 시 주의할 점
1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales
2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
REST API는 URI 경로의 마지막에는 슬래시(/)를 사용하지 않습니다.
http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments (0)
3) URI 가독성을 위해 밑줄(_)이 아닌 하이픈(-)을 사용
URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다.
4) URI 경로에는 소문자가 적합하다.
URI 경로에 대문자 사용은 피해야하는데 대소문자에 따라 다른 리소스로 인식하게 되기 때문이다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문!
RFC 3986 is the URI (Unified Resource Identifier) Syntax document
5) 파일 확장자는 URI에 포함시키지 않는다.
http://restapi.example.com/members/soccer/345/photo.jpg (X)
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키면 안된다. 아래와 같이 Accept header를 사용하도록 한다.
GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg
6) 리소스 간의 관계를 표현하는 방법
REST 리소스 간에는 연관 관계가 있을 수 있는데 이런 경우 다음과 같은 표현방법으로 사용한다.
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하면 된다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용한다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)
Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워지는데, DOCUMENT는 객체, 컬렉션은 객체들의 집합이다. 컬렉션과 도큐먼트는 모두 리소스라고 표현할 수 있으며 URI에 표현된다. 아래 URI를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있다.
http:// restapi.example.com/sports/soccer
아래 URI는 sports, players 컬렉션과 soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 이루어진다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점인데, 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있다.
http:// restapi.example.com/sports/soccer/players/13
그렇게 탄생한 API 설계서..뚜든!🏋🏻♂️
설계서를 보면 로그인/회원가입과 관련된 API 리스트는 POST /api/signin 과 GET /api/user/{userId} 이다. 하지만 signin 같은 경우는 행위이다. 위에서 RESTful 설계는 delete와 같은 행위에 대한 표현이 들어가서는 안되고 자원 members 를 표현하는데 중점을 두어야한다고 했다. 따라서 아래와 같이 수정되어야한다. (-> 로 표현된게 RESTful하게 API를 수정한 사항이다.)
올바른 예: /users
잘못된 예: /api/signinAPI 설계서(원문 보기)
이어서 200번, 400번, 500번 HTTP response 상태코드에 대한 이야기를 해볼 예정이다.
HTTP response 상태코드(2xx, 4xx, 5xx)
잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다. 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것은 중요하다. 200이나 4XX관련 특정 코드 정도만 사용하고 있다면 처리 상태에 대한 좀 더 명확한 상태코드 값을 사용해야한다.
🤓 언제 어떤 응답상태코드를 쓰는가??
가장 많이 쓰이는 상태코드는 아래와 같다..❗️이 중에 가장 주니어 개발자들이 헷깔려하는 부분이 204의 의미인데, 예시로 이해하면 좋다. '크로스핏🏋🏻♂️ 용어 맞추기 웹 서비스'의 경우 문제를 다 풀고 댓글을 적을 수 있는데 댓글 리스트 요청을 클라이언트가 할 때 해당 문제에 댓글이 있을 수도 있고, 없을 수도 있다. 아직 아무도 댓글을 쓰지 않았을 경우가 정상인데 데이터가 없는 경우가 되고 이때의 상태코드는 204 No Content 가 된다. 그러다가 어떤 사용자가 해당 문제에 댓글을 달게 되면 댓글 리스트에 1개의 댓글 데이터가 생기고 이 경우 200번 OK 데이터가 있음이 상태응답코드가 된다.
데이터가 있음(정상, 데이터가 있음): 200 OK
데이터가 성공적으로 요청 및 생성(POST 요청의 경우): 201 OK
특정 리소스가 있을 수도 있고, 없을 수도 있음 (정상, 데이터가 없음): 204 No Content
클라이언트가 말도 안되는 파라미터로 리소스를 요청함(실패, 클라이언트에서 넘어온 파라미터가 이상함): 400 Bad Request
정말 존재하지 않는 uri 임(실패, 데이터가 있어야 하나 없음): 404 Not Found
특정 리소스가 있어야하는데 없음 (서버 로직 문제, 서버 내부 오류): 500 Internal Server Error
그 밖에 다양한 응답상태코드입니당 👀
그렇지만.. 참고만 하세요. 😱 포트폴리오 프로젝트의 경우는 위의 정도로 나누면 충분해요!
✨ 개발 멘토가 PM이 되어 내 포트폴리오 프로젝트를 만드는 프로그램이 궁금하시다면?
포트폴리오 4주 동안의 과정을 더 자세히 살펴볼까요? 🏋🏻♂️
포트폴리오 4주 만에 준비하기 <시작하기>
포트폴리오 4주 만에 준비하기 QnA
포트폴리오 4주 만에 준비하기👩🏻💻<첫번째> 아이템 선정
포트폴리오 4주 만에 준비하기👩🏻💻<두번째> 기능 정의하기
포트폴리오 4주 만에 준비하기👩🏻💻<세번째> DB 모델링하기
포트폴리오 4주 만에 준비하기👩🏻💻<네번째> API 설계하기
