2. Tutorials
  3. hapi — Query Parameter Validation With Joi

hapi — Query Parameter Validation With Joi

As an application developer, you should never trust the data provided by users. At any possible input! That doesn’t only apply for request payload send within the request body, but also for query parameters.

This guide shows you how to apply query parameter validation for a given route in your hapi server using the joi plugin.

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

Prepare Your Project and Install Joi

You’ll use the joi module from within hapi’s plugin ecosystem to validate provided query parameters on a given route. Before defining the validation itself, you need to add joi as a dependency to your project:

npm i -S joi

Installation process finished successfully? Your project is ready to make use of joi for input validation.

Use Joi for Query Parameter Validation

Query parameters aren’t defined within your route setup and users can provide any kind of value if they know what parameter keys you’re evaluating and processing within your app. Within the following code snippet, you can see how the actual query parameter validation is applied to a specific route.

In case you’ve the query parameter validation configured, hapi applies the defined constraints. Depending on whether the given parameter data passes the validation process successfully, the request will be proceeded by calling the route handler. If validation already fails, hapi will reply with a detailed boom error object including the reason why validation didn’t finish correctly.

var Joi = require('joi')

server.route({  
  method: 'GET',
  path: '/tutorials',
  config: {
    handler: …,
    validate: {
      query: {
        filter: Joi.array().items(Joi.string().valid('premium', 'video')).single()
      }
    }
  }
})

As you can see within the code snippet above, to enable validation on your route, you need to define a config.validate object. The query parameter validation is used with the help of the query property.

The snippet shows an exemplary query parameter validation for the filter key, like https://futurestud.io/tutorials?filter=video. The actual validation rule looks kind of complex, but it just says that users are only allowed to use the premium or video or both values with the filter parameter. If users provide other values than allowed, the validation will fail and users will see an error message.

You can find all applicable methods and constraints within joi’s API reference.

Notice: if you apply validation for one of your query parameters, you need to define rules for every other as well. Joi will validate every query parameter if you’re activating one or many for a given route. If you’re going to use the route from above, you can’t use another query parameter (like ?page=20), because joi only expects filter.

Validate Multiple Query Parameters on a Route

In the paragraph above, you’ve read that if you apply validation to a single query parameter, you need to validate all of them. And that’s kind of straight forward by adding your query parameter keys to the validate.query object in your hapi route.

Let’s extend the previous example with another query parameter, called page. Assumingly you’re going to use the page parameter for pagination through your list of tutorials. That means you’re expecting a number greater than zero.

validate: {  
  query: {
    filter: Joi.array().items(Joi.string().valid('premium', 'video')).single(),
    page: Joi.number().min(1)
  }
}

If you want to validate further query parameters, just add them to the query object within validate.

Outlook

We hope you see the need and benefits of query parameter validation in your hapi project. Don’t trust user data and make sure to validate the input if there’s a chance to provide malicious information.

And please keep in mind, that once you apply validation for a single query parameter, you need to add the rules for all possible keys as well. Otherwise, the validation for those keys will fail.

To complete the validation on request data, follow along to learn the basics on path parameter validation in hapi.

Do you have any question or just want to leave a message? Use the comments below or find us on Twitter @futurestud_io

Make it rock & enjoy coding!

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous