먼저 API란 무엇인가?
정보 교환에 있어 개발자들 사이에 널리 쓰이는 일종의 형식이다.
어떤 기술이나 제품이 아닌 형식이기 때문에 어떤 언어를 쓰든, 어떤 프레임 워크를 쓰든, 어떤 프로젝트를 하든
폼에 맞춰 기능을 만드는 것이다.
하드웨어 세계에서 인터페이스로는 입출력 장치등이 있고,
소프트웨어 세계에도 제어와 조회등 사용을 돕도록 버튼이나 스크롤 바등이 존재한다.
사람과 소프트웨어, 사람과 하드웨어 간 말고도,
기계와 기계. 소프트웨어와 소프트웨어 사이에도 수많은 정보 요청과 교환이 이루어지는데, 이 사이에도 인터페이스가 필요하다.
웹사이트들이나 앱들은 특정 서버에서 실시간으로 정보를 요청해서 받아가는데,
이렇게 웹이나 앱에서 서버에 요청을 할때는 요청하는 형식, 응답받는 형식등의 매뉴얼이 존재한다.
소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청, 명령을 받을 수 있는 수단을
API, application programming interface 라고 한다.
우리가 흔히 보는 주소창의 uri 또한 api 의 일종이라고 할 수 있다.
이렇게 웹상에서만 api가 있는 건 아닌데,
로컬 프로그램인 브라우저는 web api 를 통해 js로부터 특정 동작을 지시받기도 한다.
또 윈도우는 시스템이나 하드웨어에 대한 지식 없이도 개발자가 소프트웨어를 짤 수 있게 windows api를 제공한다.
그래서 rest api란 무엇인가?
rest api 를 한마디로 말하자면,
멤버들과, 인수자들이 잘 사용할 수 있게 디자인, 설계를 하는 형식이다. 멤버들과, 인수자들이 잘 사용할 수 있음.
이런 규칙에 의해 작성된 api를 restful api 라고 한다.
어쨌건
프론트엔드 웹에서 서버에 데이터를 요청하거나, 배달앱에서 서버에 주문을 넣는 등 오늘날 서비스에서 가장 널리 사용되는것이
rest api(representational state transfer) 이다. 과거의 soap 이라는 형식을 대체 했다.
1. 동사는 없이, 오직 명사로만, 그리고 collections, element 에서 단수 복수의 사용.
rest의 가장 중요한 특성은, 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론 가능하다는 것이다.
레스트한 api는 고유의 uri로 리소스에 접근한다.
사실 기능만 중요시 생각한다면, url 과 실제 내용의 매칭을 신경 쓸 필요 없이
/create
/seemovies
/getmovie/inception
/deletemovie/inception
/updatemovie/inception
/gettopratedmovies
/findmoviesfromthisyear
이렇게 동작하게만 만들면 그만이다.
하지만 문제는 이런 api를 관리하는 개발자가 인수인계등을 통해 바뀔 수도 있고, 개발과정에서 협업이 필요할 수 있다는 것이다.
위 uri 의 문제는 같은 조회를 해도 see get find. 등, 너무 중구난방으로 적혔다.
리소스는 uri 를 통해서 표현되는데, 이런 리소스와 url는 동사가 아닌 명사로 이루어 져야한다.
위에서 동사를 다 지우고 명사만 남겨보자.
/movies
/movies
/movies/inception
/movies/inception
/movies/inception
/topratedmovies
/moviesfromthisyear
훨씬 깔끔해진 것을 볼 수 있다.
다음으로 collection과 element 개념이 있다. 엘리먼트 리소스 전체를 아우르는 movie는 collection으로써 복수형태로 적어줘야 한다.
그리고 collection 하에서, 아이디로 식별하는게 일반적이나, 이름으로 식별하게 된다면 단수형으로 사용한다.
위의 예에서는 영화명이기 때문에 단복수가 따로 없다.
이렇게 하면 같은 uri 라도 http 메소드에 따라 다른 동작이 가능하다. 훨씬 간결해지는 것이다.
2. 쿼리 파라미터를 적절히 이용한다.
/topratedmovies
/moviesfromthisyear 의 uri 를 쿼리파라미터를 이용해
movies?min_rating=9.8, /movies?release_date=2021의 형태로 바꾼다고 생각해보자.
각자의 uri 를 만드는 것보다 훨씬 개선된 방식이다.
이는 페이지 네이션과도 연결되는데
엄청난 량의 페이지를 다룰때는 페이지네이션을 써야한다.
/products?limit=25&offset=50
디폴트 값이 들어가지 않도록 패러미터등도 구체화해주는 것이좋다.
3. http 메소드 5가지를 상황에따라 적절히 사용한다.
서버에 api로 요청을 보낼때는 http 란 규약에 따라 신호를 전송한다.
여러가지 http 메소드가 있으나 Rest api에서는 GET, POST, DELETE, PUT 등의 4가지에서 PATCH 까지 포함한 5가지만을 활용한다.
이는 CRUD 기능 모두를 아우를 수 있다.
POST PUT PATCH 에는 body 라는 주머니가 있고 http 요청의 바디 부분으로 json으로 엔코딩된 사용자정의 데이타가 있을 수 있다.
즉 get delete 보다 정보를 더 많이, 그리고 비교적 안전하게 감춰서 실어 보낼 수 있다.
사실 이 기능들이 특정 용도에 제한돼 있지는 않다. POST 메소드 하나만으로도 CRUD가 모두 가능하다.
하지만 누구든 각 요청의 의도를 쉽게 파악할 수 있도록 restful 하게 api 를 만들기 위해서는 목적에 따라 이들을 구분해 사용해야한다.
get 은 데이터를 read 조회하는데 사용한다.
post는 새로운 정보를 생성하는데 사용된다. create
그런데 만약에 이미 존재하는 학정보를 수정한다면 put 또는 patch 를 사용해, 변경 또는 update 될 새 정보들을 body에 실어 보낸다.
그냥 put으로 다 하는 곳도 있는데 정석은, put은 정보를 통채로 갈아 끼울때, patch는 정보중 일부를 특정 방식으로 변경할때 사용한다.
어떤 프레임웍으로 어떤 언어로 프로젝트를 만들든 소프트웨어간 http로 정보를 주고받는 부분이 있다면 이 형식, 규칙들을 준수해서 restful한 서비스를 만드는 연습을 할 수 있다.
4. 알맞은 http 상태 코드 반환.
잘 만들어진 restful api는 적절한 http 상태 코드를 반환한다
200대의 코드는 요청이 성공적이였음을 의미한다.
400대의 코드들은 요청에서 무언가가 잘못됐다는 것을 말한다.
500대에서는 서버단계에서 문제가 생겼다는 것을 말한다.
잘 동작하는 클라이언트는 500번대 상태코드의 실패를 재시도 할 수 있어야 한다. 결과가 달라질 수도 있기 때문이다.
그리고 그걸 구현할땐 조심해야한다.
api가 재시도 불가할때, 재시도로 결과가 달라지는 요청과 달라지지 않는 요청이 있다. post만이 재시도로 결과가 달라진다.
5. 무상태여야 한다.
응답 바디에 제이슨으로 포매팅 된 데이터 페이로드를 포함될 수 있는데,
레스트 실행은 무상태여야 한다.
이것은 서버든 클라이언트든 각자에 대한 정보를 저장할 필요가 전혀 없으며, 각 요청 응답 사이클이 각자 독립적이라는 것을 의미한다.
6. uri 를 통한 버전 관리
api 버전관리도 하나의 요소가 될 수 있다.
새로운 버전이 나왔더라도, 구형을 사용할 수 있게 해줘야 한다.
가장 직접적 방법은 uri자원 이전에 버전을 표기하는 것이다.
/v1/products
/v2/products
restful api design guidelines 를 구글링 하면 더 자세한 내용을 찾아 볼 수 있다.
다른 유명 ap 옵션으로 graph ql 과 grpc 가 있다.
댓글