기게와 기계
소프트웨어와 소프트웨어
사이 수많은 요청과 정보 교환이 이루어지고 있고 이들 사이에서 소통하는 수단을 API(Application Programming Interface)라고 한다.
REST API란 ?
프론트엔드 웹에서 서버에 데이터를 요청하거나
배달 앱에서 서버에 주문을 넣는 등
이러한 서비스들에서 오늘날 널리 사용되는 것이 REST란 형식의 API다.
과거의 SOAP이란 복잡한 방식을 대체한 것.
각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능한 것.
만들고자 하는 서비스에서 기능 자체만 중요하다고 생각한다면 REST형식의 API를 생각하지 않고 동작만 하게 만들면 된다.
- https://(site-domain)/1 -> 학원의 반 리스트 요청
- https://(site-domain)/hello -> 반의 학생들 리스트 요청
- https://(site-domain)/heon -> 학생의 정보 수정 요청
이런식으로 API를 구성해도 서비스의 기능 자체에는 문제가 없을 것이다.
단. 서비스 개발은 협업이다. 당장은 혼자라도, 나중에 이 일을 인계받을 개발자나, 이 API를 사용해서 다른 제품을 만들 개발자들은 개발할 수 없을 것이다.
RESTful하게 만든 API는 요청을 보내는 주소만으로도 대략 어떤 요청인지 파악이 가능해야 한다. 학원 DB에게, 정보를 보내다랄는 요청을 할 때 주소에 classes가 붙는다면https://(site-domain)/classes -> 학원의 반들 목록을 받아오는 요청이라고 유추할 수 있다.
{
"results": [
{"idx": 1, "name": "예비반"},
{"idx": 2, "name": "초급반"},
{"idx": 3, "name": "중급반"},
{"idx": 4, "name": "고급반"}
]
}만약 https://(site-domain)/classes/2를 하게 되면 여러 반들중 idx가 2인 반의 정보를 받아오게 되는 것.
그 뒤에 students를 붙여서 보내면 2반의 학생들 정보를 받아오고,
여기에 또 인덱스(15)를 붙이면 해당 idx=15인 학생의 정보를 받아오게 됩니다.
`{"idx": 15, "name": "연흥부", "sex": "male"},
https://(site-domain)/classes/2/students**?sex=male**과 같이 sex=male을 할 경우 2반의 학생들 중 남학생들만 필터링을 해서 정보를 받아올 수 있습니다.
{
"results": [
{"idx": 1, "name": "홍길동", "sex": "male"},
{"idx": 2, "name": "전우치", "sex": "male"},
{"idx": 3, "name": "장기한", "sex": "male"},
{"idx": 4, "name": "임꺽정", "sex": "male"},
]
}또한 한 페이지에 10명씩 받아오는 거라면 아래처럼 표현이 가능합니다.
https://(site-domain)/classes/2/students?page=2?&count=10
{
"results" : [
{"idx": 11, "name": "김동헌", "sex": "male"},
{"idx": 12, "name": "김윤기", "sex": "male"},
{"idx": 13, "name": "설한나", "sex": "female"},
{"idx": 14, "name": "김민기", "sex": "male"},
...
]
}즉, 자원을 구조와 함꼐 나타내는 이런 형태의 구분자를 URI라고 합니다.
이런 조회작업 뿐 아니라, 정보를 새로 넣거나 수정하거나, 삭제하는 작업도 필요하겠죠 ?
이를 통틀어서 C.R.U.D, CRUD라고 합니다.
- CREATE 생성
- READ 조회
- UPDATE 수정
- DELETE 삭제
서버에 REST API로 요청을 보낼 때는 HTTP란 규약에 따라 신호를 전송합니다.
우체국에서 우편을 부칠때 일반우편, 등기, 택배 등 다양한 방식이 있듯이 HTTP로 요청을 보낼 때도 여러 메소드들이 있습니다.
REST API에서는 GET, POST, DELETE, PUT, PATCH를 사용합니다.
소포가 편지보다 더 많은 걸 담을 수 있듯이 POST, PUT, PATCH에는 body라는 주머니가 있어서 정보들을 GET이나 DELETE보다 많이 그리고 비교적 안전하게 감춰서 실어보낼 수 있습니다.
이것들의 기능이 특정 용도에 제한되어 있지는 않습니다. 예를들어 post 하나로도 데이터를 쓰고 수정하고 지우고까지 다 할 수 있습니다.
하지만 누구든 각 요청의 의도를 쉽게 파악할 수 있도록 RESTful하게 API를 만들기 위해서는 이들을 목적에 따라 구분해서 사용해야 합니다.
GET은 데이터를 Read, 조회하는데 사용합니다.
https://(site-domain)/classes/2/students의 URI에 get으로 보내는 요청이 있다면 2반의 학생들을 보는 요청이라고 유추할 수 있는 것이죠.
POST는 Create, 새로운 정보를 추가하는데 사용합니다.
2반의 새 학생이 들어와서 정보를 추가하려면 https://(site-domain)/classes/2/students로 URI를 짜고, post 요청을 작성해서 body에 새 학생의 정보를 실어 보냅니다.
학생의 idx는 보통 정보가 추가되면서 생성되기 때문에 post요청에서는 명기할 필요가 없습니다.
만약 idx=14의 인덱스를 가진 학생의 정보가 변경되었다면 URI에 변경할 학생의 idx까지 명기한 다음 put또는 patch를 사용해서 Update 될 새 정보들을 역시 body에 실어 보냅니다.
put과 patch의 사용은 쓰는 곳마다 다르고 그냥 PUT으로 다 하는 곳들도 있는데 알려진 정석은 put은 정보를 통째로 갈아끼울 때, Patch는 정보 중 일부를 특정 방식으로 변경할 때 사용하는겁니다. 어떤 학생이 학원을 그만 두면 delete를 써야합니다.
DELETE https//(site-domain)/classes/2/students/3을 하면 idx=3인 학생의 정보가 수정될 것입니다.
post나 put 같은 것 하나로도 용량이 적고 중요도가 낮은 정보들을 get으로만 이 4가지가 다 그낭하겠지만, 이것들로 구분 가능한 요청들을 만들어내려면
- https//(site-domain)/classes/2/students/create
- https//(site-domain)/classes/2/students/read
- https//(site-domain)/classes/2/students/update
- https//(site-domain)/classes/2/students/delete
와 같이 URI에 이들의 동작까지 명기해야 할 것입니다.
이런 것들을 지양하기 위한 REST 규칙 중 하나로 URI는 동사가 아닌 명사들로 이뤄져야 한다는 것입니다.
결국 REST API란, HTTP 요청을 보낼 때 어떤 URI에 어떤 메소드를 사용할 지 개발자들 사이에 널리 지켜지는 약속입니다.
형식이기 때문에, 기술에 구애받지 않고, 앱을 만들든 웹 사이트를 만들든 그것들은 어떤 언어로 뭘 써서 만들든 거기에 소프트웨어간 HTTP로 정보를 주고 받는 부분이 있다면 해당 포스팅의 형식, 규칙들을 준수해서 RESTful한 서비스를 만드시면 좋겠습니다.
해당 포스팅은 REST API의 기초적인 부분이며 restful api design guidelines 검색을 통해 더 자세한 내용들을 찾아보실 수 있습니다.
참고자료
