Setting up Vanya & Hoppscotch for Medplum FHIR API Interactions

A comprehensive guide to testing and interacting with your Medplum FHIR server using Hoppscotch and Vanya

Introduction

When working with FHIR APIs, having the right tools for testing and development is crucial. This guide will walk you through setting up Hoppscotch (a modern API testing tool) and Vanya Desktop Tools to interact with your Medplum FHIR server, import patient bundles, and test your API endpoints effectively.

Prerequisites

Before we begin, ensure you have: - A running Medplum server instance Medplum Dev Setup - Your Medplum server URL endpoint - Basic understanding of FHIR and REST APIs

Part 1: Setting up Hoppscotch

Step 1: Install Hoppscotch

Download and install Hoppscotch on your desktop or macOS device. Hoppscotch is a lightweight, fast alternative to Postman that's perfect for API testing.

Step 2: Import Medplum Collections

Medplum provides ready-to-use Postman collections that work seamlessly with Hoppscotch. You'll find these in the official repository:

Repository: medplum/medplum-postman-examples

Import the following files into your Hoppscotch workspace:

1. API Collection: medplum.postman_collection.json

   • Contains pre-configured API requests for common Medplum operations
   • Import this into your Hoppscotch collections section

2. Environment Variables: medplum.postman_environment.json

   • Contains environment variables for different server configurations
   • Import this to set up your environment variables

Step 3: Configure Access Tokens

Once you have the collections imported, you'll need to set up authentication.

Video Tutorial: Hoppscotch Environment and Collection Import Guide

Authentication Options

Option 1: Bearer Token Authentication - Obtain an access token from your Medplum server - Add it to your requests using the Authorization: Bearer <access_token> header

Option 2: Basic Authentication (Recommended) - Use your client_id and client_secret - Generate Basic Auth header using tools like DebugBear's Basic Auth Header Generator - This method is often more convenient for development

Part 2: Working with FHIR Data

Importing Patient Bundles

For importing FHIR Patient Bundles via REST API, use the following endpoint:

POST <base-url>/fhir/R4

This endpoint accepts FHIR Bundle resources and processes them according to the FHIR specification.

Additional Resource: Populating a FHIR Test Server - A comprehensive guide on data import strategies.

Part 3: Alternative Setup with Vanya

What is Vanya?

Vanya is a desktop application specifically designed for FHIR development and testing. It provides an intuitive interface for working with FHIR resources.

Setting up Vanya with Medplum

1. Download Vanya: Get the latest version from vanyalabs.com

2. Configuration: Follow the detailed setup guide in this blog post: Vanya and Medplum Integration

3. Authentication: Use the same Basic Auth approach mentioned above for seamless integration

Best Practices

1. Environment Management: Keep separate environments for development, testing, and production
2. Security: Never commit access tokens or secrets to version control
3. Testing: Start with simple GET requests before moving to complex POST operations
4. Documentation: Document your API calls and expected responses for team collaboration

Conclusion

With Hoppscotch and Vanya properly configured, you now have powerful tools for developing and testing against your Medplum FHIR server. These tools will streamline your development workflow and make API testing more efficient.

Whether you prefer the web-based approach of Hoppscotch or the specialized FHIR focus of Vanya, both tools integrate well with Medplum's API structure and will enhance your FHIR development experience.

---

For more advanced configurations and troubleshooting, refer to the Medplum documentation and the respective tool documentation.