매개변수는 API 또는 웹 서비스와 관련하여 자주 목격됩니다. 당신은 아마도 이 모든 시간 동안 매개변수를 사용하고 있었다는 것을 깨닫지 못할 수도 있습니다! 매개변수와 상호작용하는 일반적인 장소 중 하나는 웹사이트 URL입니다. 그러나 다양한 유형의 매개변수가 있다는 것을 알고 계신가요?
매개변수에 관심이 있다면 Apidog가 좋은 시작 선택이 될 수 있습니다. 간단하고 직관적인 UI를 통해 아래 버튼을 클릭하여 빠르게 시작하세요! 👇 👇 👇
이 글에서는 매개변수의 기초에 대해 소개한 후 경로 매개변수와 쿼리 매개변수가 무엇인지 살펴보겠습니다. 경로 매개변수가 쿼리 매개변수보다 더 선호되는 시나리오에 대한 섹션도 있을 것입니다.
기초: API의 매개변수
API에서 매개변수는 API 요청의 기능에 직접적인 영향을 미칠 수 있는 변수 요소입니다. 매개변수는 API에 특정 세부사항이나 지침을 제공하여 API가 응답에 포함할 내용을 담당하도록 합니다.
매개변수 기능
편리하게도, 다음은 매개변수가 API 개발자에게 제공할 수 있는 기능의 세 가지 포인트입니다:
- 요청 명시: 매개변수는 특정 리소스에 대해 API가 수행하기를 원하는 작업의 유형을 정의할 수 있습니다.
- 응답 사용자 정의: 매개변수는 요청에 대한 응답으로 API가 제공하는 콘텐츠 또는 형식에 영향을 미칩니다.
- 데이터 필터링: 매개변수는 API로부터 수신된 결과를 필터링하는 데 사용됩니다.
매개변수 구현의 다양한 방법
API 요청에서 매개변수를 전달하는 방법는 몇 가지가 있습니다. 이 지점에서 경로 매개변수와 쿼리 매개변수라는 용어가 등장합니다.
- URL 경로: 이러한 변수는
/users/{id}와 같이 URL 경로에 직접 통합되며, 여기서{id}는 특정 사용자 ID를 나타내는 매개변수입니다.
여기서{id}매개변수는 경로 매개변수로 지칭될 수 있습니다. - 쿼리 문자열: 쿼리 문자열은 물음표(
?) 뒤에 추가된 키-값 쌍으로,?limit=10&sort=name와 같이limit와sort는 해당 값과 연결된 매개변수입니다.
키-값 쌍인limit와sort는 쿼리 매개변수라고도 합니다. - 헤더: 요청과 함께 전송되는 추가 정보로, 인증 토큰 또는 선호하는 언어 등이 있습니다.
- 요청 본문: 복잡한 리소스 생성 또는 수정 데이터는 요청 본문에 전송될 수 있으며, 종종 JSON이나 XML과 같은 형식으로 전송됩니다.
경로 매개변수란 무엇인가요?
경로 매개변수는 API 요청의 URL 경로에 직접 포함된 요소로, 특정 값에 대한 자리 표시자 역할을 합니다. 이러한 매개변수는 API 내에서 고유한 리소스를 표적으로 하고 식별하는 데 사용됩니다.
경로 매개변수 예시
/users/{id}는 경로 매개변수의 예시입니다. 특정 사용자의 경로 매개변수를 나타냅니다(사용자는 이 예시에서 리소스입니다).
URL에서 이러한 중괄호 {}를 보게 되면, 그것은 경로 매개변수입니다. 그러나 실제로 웹사이트에서는 중괄호는 API의 작동을 위한 특정 값으로 대체되기 때문에 보이지 않습니다.
왜 경로 매개변수를 사용해야 할까요?
경로 매개변수는 고유 식별자(ID)를 기반으로 특정 데이터나 개체를 정확히 지목하는 데 주로 선택됩니다.
경로 매개변수는 URL 가독성을 높이는 훌륭한 방법입니다. URL을 더 설명적이고 자동 문서화하도록 만들어 다른 개발자들이 URL을 이해하고 그것이 의도하는 바를 이해할 수 있게 합니다.
마지막으로, 경로 매개변수는 API의 리소스 모델 내에서 계층 구조를 나타내기 위해 중첩될 수 있으므로, 중첩된 컬렉션 내에서 리소스에 접근할 수 있습니다. 이를 통해 폴더 내의 폴더를 들어가 단일 파일에 접근하는 것으로 생각할 수 있습니다.
쿼리 매개변수란 무엇인가요?
쿼리 매개변수는 다른 이름을 가지고 있습니다 - URL 매개변수 또는 쿼리 문자열. 그것들은 물음표 ? 뒤에 URL에 첨부된 추가 정보입니다.
쿼리 매개변수는 앰퍼샌드 &로 구분된 키-값 쌍으로 구성됩니다. 쿼리 매개변수는 API 요청 행동을 수정하기 위해 설계된 선택적 지침으로 언급됩니다.
쿼리 매개변수 예시
/users?sort=name&limit=10는 두 개의 쿼리 매개변수 sort와 limit로 구성된 URL 예시입니다.
이 예시에서의 키-값 쌍은 sort=name과 limit=10입니다.
왜 쿼리 매개변수를 사용해야 할까요?
경로 매개변수와 비교할 때, 쿼리 매개변수는 그 기능 때문에 더 많이 사용됩니다.
쿼리 매개변수는 다음과 같은 프로세스를 통해 API 요청의 행동을 추가 정보로 수정할 수 있습니다:
- 필터링: 특정 기준에 따라 결과를 필터링합니다 (예:
?category=electronics). - 정렬: 특정 기준에 따라 결과의 순서를 정합니다 (예:
?sort=price,desc). - 페이지 나누기: 성능 향상을 위해 더 작은 청크로 결과를 검색합니다 (예:
?page=2&per_page=20). - 검색: 키워드를 기반으로 특정 리소스를 검색합니다 (예:
?q=books).
경로 매개변수 vs 쿼리 매개변수 - 표 형식
| 특징 | 경로 매개변수 | 쿼리 매개변수 |
|---|---|---|
| 위치 | URL 경로에 포함 ({id}) |
'?' 후에 추가됨 (?sort=name&limit=10) |
| 목적 | 특정 리소스 식별 | 요청 행동 수정 (필터링, 정렬 등) |
| 필수 | 예 | 아니요 |
| 보안 | 덜 안전 (URL에 표시됨) | 약간 더 안전 (URL 경로와 분리됨) |
| 가독성 | 가독성 향상 | 가독성 감소 가능 |
| 계층 구조 | 중첩 가능 | 계층 구조에 적합하지 않음 |
2024년 완전하고 강력한 API 개발 도구 - Apidog
Apidog는 전체 API 생애 주기를 위한 다양한 사양과 수정을 용이하게 하는 올인원 API 개발 플랫폼입니다. 사용자는 Apidog 소프트웨어 내에서 API를 구축, 테스트, 디버그, 문서화 및 모의할 수 있습니다.
Apidog는 단순하면서도 직관적인 사용자 인터페이스를 소중히 여기는 사람들을 위한 훌륭한 플랫폼입니다. 경로 매개변수와 쿼리 매개변수에 익숙해지고 싶다면, Apidog는 REST API 또는 SOAP API를 가져오는 방법을 명확하게 보여주며, 이를 수정할 수 있도록 해줍니다.
Apidog로 API 파일 가져오기
API의 URL에 매개변수가 포함되는 방식을 관찰하려면 API를 Apidog로 가져와야 합니다.
당신의 API 파일에 해당하는 적절한 파일 유형을 선택하세요. 정확한 파일 유형을 찾을 수 없다면 위의 이미지에서처럼 파일을 창의 하단 부분으로 드래그하세요.
Apidog로 API 엔드포인트(API URL) 테스트하기
API를 성공적으로 가져온 후, Apidog로 요청을 보내 테스트할 수 있습니다.
화면 오른쪽에 있는 API 요청 중 하나를 선택합니다(화살표 1로 표시됨).
그러면 화살표 2가 가리키는 버튼을 클릭하여 요청을 보낼 수 있지만, 올바른 환경을 선택하거나 정확한 요청 API URL을 포함했는지 확인해야 합니다.
마지막으로 응답 섹션으로 이동하여 요청을 보낸 후 수신된 응답을 확인하고 예상한 것과 동일한지 확인하세요.
Apidog의 API URL에 매개변수 추가하기
위의 그림처럼 Params 헤더를 클릭하여 API URL에 자신의 매개변수를 추가할 수 있습니다. 매개변수를 추가할 경우, 올바른 구조(예: 경로 매개변수에 대한 중괄호 {} 및 쿼리 괄호에 대한 특정 기호 &, ?와 =를 준수해야 합니다).
결론
매개변수는 개발자에게 특정 리소스를 거대한 컬렉션에서 정확히 지목할 수 있도록 도와주는 매우 유용한 변수입니다. 경로 또는 쿼리 매개변수를 사용하여 데이터베이스에서 특정 리소스를 얻고, 업데이트하고, 필터링하는 것이 그 어느 때보다 간단해졌습니다. 비슷하게 들리더라도, 경로 매개변수는 쿼리 매개변수와 유사한 구조를 가지고 있지 않습니다. 따라서 두 시나리오에서 사용되는 서로 다른 기호와 두 매개변수가 표시하는 서로 다른 형식을 이해하는 것이 중요합니다.
Apidog는 다양한 종류의 API 파일 유형을 가져올 수 있는 올인원 API 개발 플랫폼입니다. API 개발을 둘러싼 많은 필수 서비스를 제공하는 뛰어난 API 도구입니다. 사용자가 API를 구축, 모의, 문서화 및 테스트할 수 있는 기능을 갖추고 있어 Postman 및 SwaggerHub 외에도 확실히 탄탄한 API 도구입니다.
