Skip to main content
Have a Wasp app in production? 🐝 We'll send you some swag! πŸ‘•
Version: 0.20.0

Custom HTTP API Endpoints

In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

How to Create an API​

APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

To create a Wasp API, you must:

  1. Declare the API in Wasp using the api declaration
  2. Define the API's NodeJS implementation

After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

Declaring the API in Wasp​

First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

main.wasp
// ...

apifooBar{// APIs and their implementations don't need to (but can) have the same name.
fn: import{ fooBar }from"@src/apis",
httpRoute: (GET,"/foo/bar")
}

Read more about the supported fields in the API Reference.

Defining the API's NodeJS Implementation​

After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

  1. req: Express Request object
  2. res: Express Response object
  3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
  • JavaScript
  • TypeScript
src/apis.js
exportconstfooBar=(req, res, context)=>{
 res.set("Access-Control-Allow-Origin","*");// Example of modifying headers to override Wasp default CORS middleware.
 res.json({msg:`Hello, ${context.user?"registered user":"stranger"}!`});
};

Using the API​

Using the API externally​

To use the API externally, you simply call the endpoint using the method and path you used.

For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

Using the API from the Client​

To use the API from your client, including with auth support, you can import the Axios wrapper from wasp/client/api and invoke a call. For example:

  • JavaScript
  • TypeScript
src/pages/SomePage.jsx
importReact,{ useEffect }from"react";
import{ api }from"wasp/client/api";

asyncfunctionfetchCustomRoute(){
const res =await api.get("/foo/bar");
console.log(res.data);
}

exportconstFoo=()=>{
useEffect(()=>{
fetchCustomRoute();
},[]);

return<>{/* ... */}</>;
};

Making Sure CORS Works​

APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

You can do this by defining custom middleware for your APIs in the Wasp file.

For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

main.wasp
apiNamespacefooBar{
middlewareConfigFn: import{ fooBarNamespaceMiddlewareFn }from"@src/apis",
path: "/foo"
}

And then in the implementation file (returning the default config):

  • JavaScript
  • TypeScript
src/apis.js
exportconstapiMiddleware=(config)=>{
return config;
};

We are returning the default middleware which enables CORS for all APIs under the /foo path.

For more information about middleware configuration, please see: Middleware Configuration

Using Entities in APIs​

In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

main.wasp
apifooBar{
fn: import{ fooBar }from"@src/apis",
entities: [Task],
httpRoute: (GET,"/foo/bar")
}

Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

  • JavaScript
  • TypeScript
src/apis.js
exportconstfooBar=async(req, res, context)=>{
 res.json({count:await context.entities.Task.count()});
};

The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

Streaming Responses​

You can use streaming responses to send data to the client in chunks as it becomes available. This is useful for:

  • LLM responses - Stream AI-generated content as it's produced
  • Long-running processes - Show progress updates in real-time
  • Large datasets - Send data incrementally to avoid timeouts

Creating a Streaming API​

To create a streaming API, write a function that uses Express response methods like res.write() and res.end():

main.wasp
apistreamingText{
httpRoute: (POST,"/api/streaming-example"),
fn: import{ getStreamingText }from"@src/streaming",
}

Don't forget to set up the CORS middleware. See the section explaning CORS for details.

  • JavaScript
  • TypeScript
src/streaming.js
importOpenAIfrom"openai";
const client =newOpenAI({
apiKey: process.env.OPENAI_API_KEY,
});

exportconstgetStreamingText=async(req, res)=>{
const{ message }= req.body;

// Set appropriate headers for streaming.
 res.setHeader("Content-Type","text/plain; charset=utf-8");
 res.setHeader("Transfer-Encoding","chunked");

const stream =await client.responses.create({
model:"gpt-5",
input:`Funny response to "${message}"`,
stream:true,
});

forawait(const chunk of stream){
if(chunk.type==="response.output_text.delta"){
// Write each chunk to the response as it arrives.
 res.write(chunk.delta);
}
}

// End the response.
 res.end();
};

Consuming Streaming Responses​

There are two ways you can consume streaming responses on the client side: using the Fetch API or using Axios.

We recommend using the Fetch API becuase it supports streaming natively. You'll need to handle auth manually by adding the Authorization header.

Axios doesn't natively support streaming responses and you have use the onDownloadProgress callback to simulate it. Wasp internally uses Axios and exposes an Axios wrapper via wasp/client/api which handles auth automatically.

Using the Fetch API​

Here's an example showing how to consume streaming responses using the Fetch API:

  • JavaScript
  • TypeScript
src/StreamingPage.jsx
import{ useEffect, useState }from"react";
import{ config }from"wasp/client";
import{ getSessionId }from"wasp/client/api";

exportfunctionStreamingPage(){
const{ response }=useTextStream("/api/streaming-example",{
message:"Best Office episode?",
});

return(
<div>
<h1>Streaming Example</h1>
<pre>{response}</pre>
</div>
);
}

functionuseTextStream(path, payload){
const[response, setResponse]=useState("");

useEffect(()=>{
const controller =newAbortController();

fetchStream(
 path,
 payload,
(chunk)=>{
setResponse((prev)=> prev + chunk);
},
 controller.signal,
);

return()=>{
 controller.abort();
};
},[path]);

return{ response };
}

asyncfunctionfetchStream(path, payload, onData, signal){
const sessionId =getSessionId();

try{
const response =awaitfetch(config.apiUrl+ path,{
method:"POST",
headers:{
"Content-Type":"application/json",
...(sessionId &&{Authorization:`Bearer ${sessionId}`}),
},
body:JSON.stringify(payload),
 signal,
});

if(!response.ok){
thrownewError(`HTTP error! status: ${response.status}`);
}

if(response.body===null){
thrownewError("Stream body is null");
}

const stream = response.body.pipeThrough(newTextDecoderStream());
const reader = stream.getReader();
while(true){
const{ done, value }=await reader.read();
if(done){
break;
}
onData(value);
}
}catch(error){
if(error instanceofError){
if(error.name==="AbortError"){
// Fetch was aborted, no need to log an error
return;
}
console.error("Fetch error:", error.message);
}else{
throw error;
}
}
}

Using Axios​

Here's an example showing how to consume streaming responses using the Axios wrapper from wasp/client/api:

  • JavaScript
  • TypeScript
src/AxiosStreamingPage.jsx
import{ useEffect, useState }from"react";
import{ api }from"wasp/client/api";

exportfunctionStreamingPage(){
const{ response }=useAxiosTextStream("/api/streaming-example",{
message:"Best Office episode?",
});

return(
<div>
<h1>Axios Streaming</h1>
<pre>{response}</pre>
</div>
);
}

functionuseAxiosTextStream(path, payload){
const[response, setResponse]=useState("");

useEffect(()=>{
const controller =newAbortController();

fetchAxiosStream(
 path,
 payload,
(data)=>{
setResponse(data);
},
 controller.signal,
);

return()=>{
 controller.abort();
};
},[path]);

return{ response };
}

asyncfunctionfetchAxiosStream(path, payload, onData, signal){
try{
returnawait api.post(path, payload,{
responseType:"stream",
 signal,
onDownloadProgress:(progressEvent)=>{
const xhr = progressEvent.event.target;
onData(xhr.responseText);
},
});
}catch(error){
if(error instanceofError){
if(error.name==="CanceledError"){
// Request was cancelled, no action needed
}else{
console.error("Fetch error:", error);
}
}else{
throw error;
}
}
}

API Reference​

main.wasp
apifooBar{
fn: import{ fooBar }from"@src/apis",
httpRoute: (GET,"/foo/bar"),
entities: [Task],
auth: true,
middlewareConfigFn: import{ apiMiddleware }from"@src/apis"
}

The api declaration has the following fields:

  • fn: ExtImport required

    The import statement of the APIs NodeJs implementation.

  • httpRoute: (HttpMethod, string) required

    The HTTP (method, path) pair, where the method can be one of:

    • ALL, GET, POST, PUT or DELETE
    • and path is an Express path string.

  • entities: [Entity]

    A list of entities you wish to use inside your API. You can read more about it here.

  • auth: bool

    If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

  • middlewareConfigFn: ExtImport

    The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /