You search a shop for a “standing desk”. To check the result, you want to send the same search directly to its API. You have the search address, but where do you put the words Standing Desk, including the space?

In the previous lesson, you checked whether a response arrived. You still send a GET request here. Now you need to check that its address asks for the search you intended, because a successful response can answer the wrong search.

Tell the search API what to look for

Start with one word so there is no space to handle yet. This request asks TestKru, the course’s practice API, to search for guide:

Method: GET
URL: https://testkru.com/api/search?query=guide

Read the address from the start. https://testkru.com takes the request to TestKru. We use this as the base URL, the starting address to which we add the part we want to use. The assignment calls this starting part the origin.

After that, /api/search chooses TestKru’s search. This is the path, just as /api/users chose the user list in the GET lesson. The path starts at the slash after testkru.com and stops before the question mark.

Choosing search still leaves a question: what should TestKru search for? The address answers it with query=guide. Read that as “search for guide.” TestKru uses the name query for its search text, and the equals sign connects that name to the text guide.

The question mark tells TestKru where these extra instructions begin. The text after it, query=guide, is the query string. A named instruction such as query=guide is a query parameter: here its name is query and its value is guide.

Keep those two uses of query separate. The query string is the whole section after ?. The word query inside it is a parameter name chosen by TestKru. Another API might call its search parameter q or search; you must use the name that API accepts.

Add a second instruction with an ampersand

TestKru can also restrict a search to a category. Add category=products to ask for products that match guide:

Method: GET
URL: https://testkru.com/api/search?query=guide&category=products

The ampersand (&) separates the two parameters. TestKru reads them as two instructions:

  • query=guide: search for guide.
  • category=products: keep matches from the products category.

The query string now contains both instructions, query=guide&category=products. The base URL and path have stayed the same. The added category tells TestKru which matches to keep.

One URL, two search instructions The base URL contacts TestKru, the path selects search, and the query string contains a search parameter and a category parameter separated by an ampersand. One URL, two search instructions https://testkru.com/api/search?query=guide&category=productsBase URLhttps://testkru.comContact TestKruPath/api/searchChoose searchStart of query?Instructions beginQuery string: all the text after ?Search parameterquery=guideSearch for "guide"Category parametercategory=productsKeep product matches&splitsEach name=value is one parameter. The & separates the two parameters.

Read what the search found

Compare the two searches using their full requests and results. Start with query=guide, without a category parameter:

Method: GET
URL: https://testkru.com/api/search?query=guide

This request returned status 200 and two items: Clean Code and Java Programming Book. Both response examples below show only the fields needed for this comparison; the other response fields are omitted:

{
  "data": [
    { "name": "Clean Code" },
    { "name": "Java Programming Book" }
  ],
  "meta": { "total": 2 }
}

The ‘data’ array lists the returned items. Each item is a JSON object, and its ‘name’ tells you which item came back. The ‘meta’ object describes the search result; its ‘total’ field counts all the matches. Following ‘meta.total’ means going into ‘meta’ and reading ‘total’, using the nested-field reading from the JSON lesson.

Why did guide find those books? Their descriptions contain that word. TestKru searches the items’ names and descriptions, so a match need not have guide in its name.

Now keep the same search text and add category=products:

Method: GET
URL: https://testkru.com/api/search?query=guide&category=products

This request returned status 200 again, but only one item:

{
  "data": [
    { "name": "Java Programming Book" }
  ],
  "meta": { "total": 1 }
}

Compare the ‘data’ arrays and ‘total’ values. Java Programming Book appears in both results, but Clean Code has disappeared and ‘total’ has dropped from 2 to 1. Clean Code belongs to the books category, so the extra parameter removed it from the products-only result.

Read ‘meta.total’ when you need the number of matches. A search can show only some matches on one page, so counting the objects in ‘data’ may give a smaller number. If ‘data’ is empty and ‘total’ is 0, the search found no matches. That can still be a successful request with status 200.

Put a space into the search text

Return to Standing Desk, the search from the opening. You cannot put a plain space into the URL as it travels to the server. Some tools replace a space for you; others reject the address. Write the space as %20:

Method: GET
URL: https://testkru.com/api/search?query=Standing%20Desk

Writing a character in this form is called URL encoding. %20 represents one space. TestKru reads the parameter’s value as Standing Desk, with a space between the words, and searches for that text. This request returned status 200, the Standing Desk item, and ‘total’ 1.

The % starts an encoded character. The two characters after it identify which character to read. You use the code for the character you want: %20 for a space, for example. Do this replacement inside your search text; leave the ? before query and the = after it unchanged, because they still mark where the search instruction begins.

Keep an ampersand inside one search value

An ampersand already separates parameters, as you saw with category=products. Suppose your search text itself contains one: guide&Java, with no spaces. If you put that text straight after query=, you get:

Method: GET
URL: https://testkru.com/api/search?query=guide&Java

TestKru separates the text at &. The request now contains:

  • Parameter named query: value guide.
  • A separate parameter named Java: TestKru does not use it as search text.

So TestKru searches for guide. Java has stopped being part of that value. This request returned the same two items as guide alone: Clean Code and Java Programming Book.

To search for the whole text guide&Java, replace the ampersand inside the value with %26:

Method: GET
URL: https://testkru.com/api/search?query=guide%26Java

This request contains one search parameter:

  • Parameter named query: value guide&Java.

TestKru reads %26 as an ampersand within that value. The response had status 200, an empty ‘data’ array, and ‘total’ 0. No item matched the complete text guide&Java. The earlier request found items because it searched only for guide.

Keep & inside the search text A plain ampersand splits query=guide&Java into two parameters, while percent-encoding it as %26 keeps guide&Java together as one search value. Keep & inside the search text PLAIN &%26Search for "guide&Java"How do youwrite the &?Two parametersquery=guide&JavaSearch text: "guide"Java is separate; TestKru ignores it.One search parameterquery=guide%26JavaSearch text: "guide&Java"The & stays inside the search value.Only the query string is shown. The base URL and path stay the same.

If your text is guide & Java, with a space on each side of the ampersand, replace those spaces too. The value becomes guide%20%26%20Java. It still represents one search text, guide & Java.

Send a real plus sign

TestKru reads a plain + in a query parameter’s value as a space. A request with query=Standing+Desk therefore found the same Standing Desk item as query=Standing%20Desk.

If you mean the plus sign itself, write %2B:

Method: GET
URL: https://testkru.com/api/search?query=Standing%2BDesk

Here the value is Standing+Desk, with a plus sign between the words. The response had status 200 and ‘total’ 0. TestKru found no item containing that text. Use %20 when you mean a space and %2B when you mean a plus sign.

Send a hash sign as search text

You may have clicked a link that jumps to a section on a long web page. Imagine an invented cooking page with this address:

https://cook.example.test/soup#ingredients

The browser asks the server for /soup. Once it has the page, the browser uses #ingredients to jump to the section marked ingredients. The part starting with # is called a fragment. It tells the browser where to go within the page, so the browser keeps that part for its own use and sends the server the address before it.

That same rule applies when you open an API URL in a browser. If you try to search for guide#Java with this address, the browser treats #Java as a fragment:

Method: GET
URL: https://testkru.com/api/search?query=guide#Java

The two sides use different parts of the address:

  • The browser keeps #Java as the fragment.
  • The server receives /api/search?query=guide, so its search value is guide.

The hash sign and Java never become part of the search text sent to the server. A live check with curl, the request tool shown in the previous lesson, also removed the fragment and returned the two guide matches.

To include the hash sign in your search, replace it with %23:

Method: GET
URL: https://testkru.com/api/search?query=guide%23Java

There is now no plain # to start a fragment. TestKru receives the encoded value and reads it as guide#Java. That request returned status 200 and ‘total’ 0, because no item matched the complete text.

What reaches the server? The browser keeps #Java as a fragment and sends only query=guide, but sends %23Java in the encoded query so TestKru searches for guide#Java. What reaches the server? GET REQUESTGET REQUESTBrowserTestKru serverPlain # starts a fragmentquery=guide#Java#Java stays in the browserServer receives/api/search?query=guideSearch text: "guide"%23 sends a hash signquery=guide%23JavaNo fragment to keepServer receives/api/search?query=guide%23JavaSearch text: "guide#Java"Two separate requests: plain # stays local; %23 becomes part of the search value.

Build the value, then add it to the URL

You also know two symbols that organize a search URL: ? begins the query string, and = connects a parameter name to its value. When you want either symbol in your search text, write %3F for a question mark or %3D for an equals sign. For example, query=guide%3F searches for guide?, and query=guide%3DJava searches for guide=Java.

An extra question mark or equals sign inside a value does not necessarily split it. Using these codes makes your intention explicit: the symbol belongs to the search text. Keep the ? that starts the query string and the = that connects query to its value in their ordinary form.

Here are the replacements used in this lesson. Apply them to characters inside the value, according to the text you want to search for:

Character in your search textWrite in the value
Space%20
Ampersand &%26
Plus sign +%2B
Question mark ?%3F
Equals sign =%3D
Hash sign #%23

For a search such as guide & Java, write the value first: guide%20%26%20Java. Then put that value after query=. Your complete URL is https://testkru.com/api/search?query=guide%20%26%20Java. If you add another parameter, use an ordinary & between the parameters, as with the category search.

You can now separate the address that chooses search from the text that search uses. The assignment applies this to two searches for sample people: one with a space and one with spaces and an ampersand. You will read each result and identify the path in the URL you sent.

Work through the assignment with two searches

Continue practicing: Build a URL and encode search text

Open the assignment and choose Sign in to practise, or Create an account first if you need one. Your CodeKru account saves your work. These public TestKru searches need no separate API login.

In the practice area, Request step chooses which search you are working on. Prepare this request fills Method and Request URL for that step. Check those settings, then use Send request to contact TestKru. Your job is to send both searches, select both responses, and enter two totals and a path.

Send and read the first search

  1. Choose GET /search?query=John%20Doe in Request step, then click Prepare this request. Check that Method is GET. The step label is shorter than the full address shown in Request URL.
  2. Read that full address before sending. Find the base URL, then the path ending before ?, then the query string. %20 puts a space between the two words in the search value. Leave Headers as prepared and Request body empty.
  3. Click Send request. Under Response from TestKru, read the status after HTTP, then read Response body. Go into ‘meta’ and find ‘total’; use that number instead of counting the items in ‘data’. An empty list can still be a successful search.
  4. Click Use this response to select this request’s evidence. The page confirms “Request selected.” Your answers will be checked against the response you selected.

Send and read the second search

  1. Choose GET /search?query=John%20%26%20Jane in Request step. Click Prepare this request again. Choosing a different step changes the guide but does not replace the console’s URL until you prepare it.
  2. Check Request URL. The two %20 codes represent spaces, and %26 keeps the ampersand inside the same search value. Keep GET, the prepared headers, and the empty body.
  3. Click Send request, read the status and ‘meta.total’ in this response, then click Use this response. Keep this total matched to the second search.

Enter the answers and save your work

Find Review your evidence and answer. The two evidence selectors are labelled with their request names. Each offers Choose a recorded request and your recorded attempts. Check that each selector refers to the response you meant to use, then read the selected responses shown there.

Fill the three answer fields from that evidence:

  • Total for John Doe: read ‘total’ inside ‘meta’ in the first search’s selected response.
  • Total for John & Jane: read the same field in the second search’s selected response. Enter each total as a number without quotation marks.
  • Resource path without the query: copy the path from the full URL you sent. Start at the slash after the website name and stop before the question mark. Leave out the base URL and the query string.

Click Submit Answers. When every check passes, the page shows “Assignment complete” with a saved 100/100 and offers Continue to lesson 6.

If a check shows Needs attention, read its note and compare your answer with the selected response it names. For a total mismatch, check that you used the right search’s ‘meta.total’. For a path mismatch, check the start and end of what you copied. If evidence is missing, prepare and send that request again, then select its response before submitting.

If you receive no response, read the tool’s message and check the URL and your connection, as in the previous lesson. If the page says your request does not match the chosen step, choose that step and use Prepare this request to restore its settings before sending again.

Try the plus-sign self-review

Under Self-review and independent variation, the page asks you to construct a query containing a literal +, meaning the plus sign itself, and inspect which text the server searched.

Use the first assignment search as your starting point. Prepare it, then replace its %20 with %2B in Request URL and send it. Compare the new response’s total and item names with the first search’s response. Explain which text each address asks TestKru to search for. This extra exercise has no answer field; keep the two required responses selected for the main assignment.

The next lesson changes the request method while keeping the address. You will compare what different methods ask the server to do and what TestKru actually returns.