The Web API Framework in DataFlex
Lesson 6 - Building a custom endpoint
In this lesson, we’ll walk you through building a custom REST API endpoint with DataFlex. Custom endpoints give you full control over HTTP methods (GET, POST, PATCH, DELETE) and let you integrate your own logic plus include it directly in the OpenAPI specification. Let’s dive in!
- Step 1: Understand the Basics
Custom endpoints in DataFlex work like the old HTTP handlers. You implement the OnHttpGet, OnHttpPost, OnHttpPut, OnHttpPatch and OnHttpDelete events yourself. But the magic here? You can also define your endpoint’s structure in the OpenAPI spec by filling the endpoint definition struct inside the OnDefineSchema event. - Step 2: Locate the Custom endpoint code in the example workspace
In the example workspace, Open MyRestAPI.Wo. Scroll down past the basic auth router — you’ll find the example custom endpoint. Inside, you’ll see placeholder handlers for OnHttpPost and OnHttpGet. Right now, they just return a simple string. We’ll upgrade this with real logic and API schema definitions. - Step 3: Define Your Endpoint Schema
To add your custom logic and the OpenAPI spec, you’ll fill the endpoint definition struct with three main parts:- Field Definitions: Define request or response body fields.
- Verb Definitions: Describe HTTP verbs like GET, POST, PATCH.
- Parameter Definitions: Define query or header parameters.
- Step 4: Add a Binary Image Upload Field
Since we want to upload images, we start by defining an image field:- Name it image.
- Set its type to binary so browsers know to show a file dialog.
- Mark it as required for POST requests.
- This tells the OpenAPI spec: “Hey, this endpoint expects an image file!”
- Step 5: Define a Query Parameter
Next, add a query parameter to associate the image with a person:- Name it personId.
- Describe it (e.g., “ID of the person”).
- Specify it’s a query parameter (not header).
- Set its type to integer.
- Mark it required.
- This means GET and POST requests expect a personId in the URL query string.
- Step 6: Define the Response Field
Tell the API what to expect in the response:- Define the image field as a response.
- Set the status code to 200 OK.
- Set the response type to application/octet-stream (commonly used for binary data).
- Step 7: Configure HTTP Verbs
Use generic verb info for shared parameters, then specify differences:- For POST, allow request content types: application/octet-stream and image/jpeg.
- Indicate that the image field is part of the POST request body.
- Assign the GET and POST verb definitions to your endpoint.
- Add descriptions:
- GET: “Retrieve the image for a person.”
- POST: “Upload a new image for a person.”
- Step 8: Finalize Your Endpoint Definition
Add both GET and POST verb definitions to your endpoint struct — that’s it! You’ve built the full schema. - Step 9: Check Your OpenAPI Spec in the Browser
- Reload your OpenAPI spec page. Under Basic Auth > Custom Logic Endpoints:
- The GET endpoint asks for the personId query parameter and shows the expected binary response.
- The POST endpoint shows a request body with the file upload dialog ready.
- Try it out! (Note: the actual implementation logic is still a placeholder, so you’ll just get the simple response string for now.)
- Step 10: Next Steps & Where to Find More
- Congrats, you’ve seen how easy it is to build and expose custom REST API endpoints in DataFlex — fully documented in OpenAPI, ready to use!
- Download the latest library from GitHub or the DataFlex Download Center.
- Have questions? Join the conversation on the DataFlex forums.
Thanks for watching and happy coding with DataFlex!
REFERENCE LIBRARY
