När ett API ska designas är ett vanligt use case att hämta information från det bakomliggande systemet. I det enklaste fallet kan vi sätta upp en resurs, med tydligt innehåll, som kan anropas för att hämta alla instanser av resursen.
GET /airplanes
Detta anrop ska då ge en kollektion av instansen airplane, med alla som finns i systemet. Men ofta är man ute efter en specifik instans, eller en delmängd baserat på indata som man är intresserad av. För att kunna fråga efter en specifik instans anger man det i URI som identifierare för resursen.
GET /airplanes/1a2b3c
Om man inte har identifieraren utan vill söka ut ett eller flera svar, går det att göra på olika sätt. Det mest vanliga sättet är att använda query parametrar för att filtrera sina svar, och därmed få ut en delmängd av den kollektion av resursen som finns i system. En tumregel att använda är att om två olika anrop ska returnera samma typ av information, då är det samma resurs som ska anropas. När du designar ditt API bestämmer du vilka fält som ska vara sökbara.
GET /airplanes?manufacturer=Boeing
Vilket ska ge en kollektion av samma informationsobjekt, men enbart med de fall då fältet manufacturer har värdet Boeing. Om man vill ge möjlighet för ytterligare filtrering går det bra att kombinera flera query parametrar.
GET /airplanes?manufacturer=Boeing&propulsion=jet
Alla dessa anrop jobbar med samma resurs, så samma informationsobjekt returneras. Men med hjälp av query paramterar har vi lyckats filtrera ner mängden till att returnera endast de instanser som är relevanta i vårt aktuella fall.