RestfulAPI(3) URL parameters

gitbook을 사용해서 프로젝트에 사용될 api를 정리하면서 path, query, body, header, cookie, body 등을 파라미터로 선택할 수 있었다.

특히 GET요청을 보낼때에는 body를 포함할 수 없기 때문에, 서버에 요청하는 리소스에 대한 정보를 path, query로 전달해야한다.

이때 어떤 파라미터를 사용해야하는지 정리해보려고 한다.

Path

path는 엔드포인트의 URI 내에 존재하며 호출범위를 하나의 개별 리소스로 축소한다. 예를들어 /vmware/vm/1이라고 작성했했다면, id가 1인 데이터만 받아온다는 의미이다.

리소스 콜렉션 중 식별자로 특정 데이터 정보만 받아올 경우 path를 사용한다.

Query

많은 리소스들 중에서 특정한 조건을 만족하는 데이터만 받아오고 싶을때, query를 사용한다. 쿼리는 키-벨류가 한쌍이며, 여러개의 쿼리는 &(ampersand)로 이어 작성한다.

path와 마찬가지로 특정 데이터만 가져오지만, path로 필터링 데이터라도 특정한 조건을 만족하는 데이터만 가져오거나, path로 필터링을 하지 않아도 특정 조건들을 만족하는 데이터만 가져올때 사용한다.

//필터링 조건이 1개인 경우
/vmware/vm?is_relic=true
//필터링 조건이 2개인 경우
/vmware/vm?is_relic=true&sort_by=effectiveSlaDomainName

Path vs Query

정리해보면, 다음과 같다.

만약 리소스를 식별하고 싶다면 Path를 사용하고, 정렬하거나 필터링하고 싶다면 Query를 사용하는 것이 바람직하다.

//fetch a list of users
/users 

//fetch a list of programmer user
/users?occupation=programmer

//fetch a user who has id 123
/users/123

express.Router()에서 path, query 표현하기

• client에서 path로 보낸 것은 서버에서 req.params로 받는다.
• 서버에서 path는 /:id등으로 표현한다.

const express = require('express');
const router = express.Router();

// GET/articles/1
router.get('/articles/:id', (req,res)=>{
  res.send(req.params.id);
});

// GET/articles/1/topics/2
router.get('articles/:articleId/topics/:topicsId', (req,res)=>{
  res.send(req.params.articleId, req.params.topicsId);
});

• client에서 query로 보낸 것은 서버에서 req.query로 받는다.
• 서버에서 query는 따로 표시하지 않는다.

const express = require('express');
const router = express.Router();

//GET/articles?title=restful
router.get('/articles', (req,res)=>{
  res.send(req.query.title);
});

//GET/articles?title=restful&page=300
router.get('/articles', (req,res)=>{
  res.send(req.query.title, req.query.page);
});

reference

• https://medium.com/@fullsour/when-should-you-use-path-variable-and-query-parameter-a346790e8a6d
• https://wahlnetwork.com/2017/09/25/working-with-restful-api-query-body-and-path-parameters/
• http://expressjs.com/en/api.html#req