API Parameters

What are API Parameters?

Parameters are empty places in memory to store variables or arguments. When building web applications, parameters are a fundamental part of the API design and function. For example, when designing your e-commerce shop, you know you'll need an `itemCost` parameter, a `shippingCost` parameter, and a `location` parameter to calculate the `salesTax` parameter. Any resource that is potentially variable requires a parameter.

Parts of an API Parameter

According to the [Open API 3 specification](https://swagger.io/specification/), to describe a parameter, you specify its name, location, data type (defined by either schema or content), and other attributes, such as description or required. Here is an example of a path parameter:

paths:
  /users/{userId}: # parameter name
    get:
      summary: 
      parameters:
        - in: # location
          name: userId
          schema:
            type: integer # data type
          required: true 
          description: Numeric ID of the user to get

Types of Parameters in API

There are multiple types of parameters:  

• Path parameters, such as `/users/{id}`. These point to a specific resource. In this case, they're pointing to a specific user's ID number.
• Query parameters, such as `/users?role=admin` The query parameter defines sort, pagination, or filter operations. See Query Parameters for more information.
• Header parameters, such as `X-MyHeader: Value` Header parameters are most often used in API security and authentication. See API Authentication for more information on using API tokens in your header parameters.
• Request body parameters, which look similar to query parameters, are most often used in POST requests to send values in the request body.
• Cookie parameters, which are passed in the `Cookie` header, such as `Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU` A cookie is an HTTP request header that contains the cookies previously sent by the server using `set-cookies`.

How do I use Parameters in API?

Parameters house variables, so think of building parameters into your API as similar to declaring a function in C, then passing values to that function. Remember, there are different kinds of parameters for different uses, and all have their own definitions. Let's try a quick example below.

Let's say we want a list of random words. We can call the Random Words API in our terminal via cURL using `curl https://random-word-api.herokuapp.com/word?number=10` to get a list of ten random words. `/word` is a path parameter, which tells us where the information can be found. The `?` tells us where the query parameter begins. The number `10` is a variable, housed in the query parameter `number=`. You can change this number to list as many words as you want, even using `/all` to list all the random words the API contains. (If you're wondering, that list is 2115215 words long!) Another query parameter, `/?swear=0`, turns off swear words, in case you're using the Random Words API to teach young people computer science.  

Conclusion

Parameters are a fundamental part of computer science, and understanding how users interact with your system will make you a better programmer and a better system designer.