Reference for the EXpress REST API.
+
+
+
+
+
+ Nearle Express API
+
+
+
+ A comprehensive platform for managing tenants, users, partners, customers,
+ orders, deliveries, products, invoices, and payments across the Express network.
+
+
+
+
Base URLs
+
+
+
Hasura API
+
{LEGACY_BASE_URL}
+
+
+
REST API
+
{REST_BASE_URL}
+
-
- Welcome to the EXpress API documentation. The EXpress API exposes the operations
- you need to manage tenants, users, partners, customers, orders, deliveries,
- products, invoices, and payments across the platform.
-
+
+ {allTopics.map((topic, index) => {
+ const Icon = topicIcons[topic.id] || Zap
+ return (
+
setActiveTopic(topic)}
+ className="group relative bg-white p-6 rounded-2xl border border-slate-200/60 shadow-sm hover:shadow-xl hover:shadow-brand-500/5 hover:border-brand-200 transition-all duration-300 cursor-pointer overflow-hidden"
+ style={{ animationDelay: `${index * 100}ms` }}
+ >
+
-
-
-
-
-
{topics.length}
-
-
-
-
-
{endpointCount}
-
-
+
+
+
+
+ {topic.name}
+
+
+
+ {topic.type === 'legacy' ? 'Hasura' : 'REST'}
+
+ {topic.endpoints.length} endpoint{topic.endpoints.length !== 1 ? 's' : ''}
+
+
+ {topic.description}
+
+
+
+ )
+ })}
-
Base URL
-
- {BASE_URL}
-
+
+
+
+ Explore interactive endpoints for both Hasura and REST APIs. All requests route through the dev proxy which injects authentication headers securely.
+
+
-
Reference layout
-
- Endpoints are grouped in the sidebar by their URL segment after
- {' '}/api/rest/xpress/.
- Pick a topic on the left to see all endpoints under it, each with its method,
- full URL, and a short description.
-
)
}
diff --git a/src/components/Sidebar.jsx b/src/components/Sidebar.jsx
index 357c162..150fe0c 100644
--- a/src/components/Sidebar.jsx
+++ b/src/components/Sidebar.jsx
@@ -1,19 +1,58 @@
import { useState } from 'react'
-import { Search, Zap, ChevronDown, ChevronRight, Terminal } from 'lucide-react'
+import { Search, ChevronRight, ChevronDown, Layers, Terminal } from 'lucide-react'
import { getTopicIcon } from '../lib/icons'
-export default function Sidebar({ topics, activeTopic, setActiveTopic, searchQuery, setSearchQuery }) {
- const [open, setOpen] = useState({ general: true, topics: true })
+export default function Sidebar({ legacyTopics, restTopics, activeTopic, setActiveTopic, searchQuery, setSearchQuery }) {
+ const [open, setOpen] = useState({ general: true, legacy: true, rest: true })
const toggle = (k) => setOpen((s) => ({ ...s, [k]: !s[k] }))
+ const renderTopicGroup = (topics, title, key) => (
+
+
toggle(key)}
+ className="w-full flex items-center justify-between px-2 py-1.5 text-slate-800 font-semibold text-sm hover:text-brand-600 transition-colors group"
+ >
+
+ {title}
+
+ {open[key] ?
+
+ {topics.map((t) => {
+ const isActive = activeTopic?.uniqueId === t.uniqueId
+ const Icon = getTopicIcon(t.id)
+ return (
+ setActiveTopic(t)}
+ className={`w-full flex items-center gap-2.5 px-3 py-2 rounded-lg text-sm transition-all duration-200 group ${
+ isActive
+ ? 'text-brand-700 bg-brand-50 shadow-sm font-medium'
+ : 'text-slate-600 hover:text-slate-900 hover:bg-slate-100/50'
+ }`}
+ >
+
+ )
+ })}
+
+
+ )
+
return (
+
+ {/* Brand Header */}
-
-
EXpress
+
Nearle Express
@@ -29,67 +68,34 @@ export default function Sidebar({ topics, activeTopic, setActiveTopic, searchQue
+
+ {/* Getting Started */}
toggle('general')}
className="w-full flex items-center justify-between px-2 py-1.5 text-slate-800 font-semibold text-sm hover:text-brand-600 transition-colors group"
>
-
- Getting Started
-
- {open.general
- ? Getting Started
+ {open.general ?
setActiveTopic(null)}
- className={`w-full flex items-center gap-2.5 px-3 py-2 rounded-lg text-sm transition-all duration-200 ${activeTopic
- ? 'text-slate-600 hover:text-slate-900 hover:bg-slate-100/50'
- : 'text-brand-700 bg-brand-50 shadow-sm font-medium'
- }`}
+ className={`w-full flex items-center gap-2.5 px-3 py-2 rounded-lg text-sm transition-all duration-200 ${
+ activeTopic === null
+ ? 'text-brand-700 bg-brand-50 shadow-sm font-medium'
+ : 'text-slate-600 hover:text-slate-900 hover:bg-slate-100/50'
+ }`}
>
-
-
-
toggle('topics')}
- className="w-full flex items-center justify-between px-2 py-1.5 text-slate-800 font-semibold text-sm hover:text-brand-600 transition-colors group"
- >
-
- API Reference
-
- {open.topics
- ?
-
- {topics.map((t) => {
- const isActive = activeTopic?.id === t.id
- const Icon = getTopicIcon(t.id)
- return (
- setActiveTopic(t)}
- className={`w-full flex items-center gap-2.5 px-3 py-2 rounded-lg text-sm transition-all duration-200 group ${isActive
- ? 'text-brand-700 bg-brand-50 shadow-sm font-medium'
- : 'text-slate-600 hover:text-slate-900 hover:bg-slate-100/50'
- }`}
- >
-
- )
- })}
-
-
diff --git a/src/components/TopicView.jsx b/src/components/TopicView.jsx
index bebe022..f838ab8 100644
--- a/src/components/TopicView.jsx
+++ b/src/components/TopicView.jsx
@@ -1,12 +1,15 @@
import { useEffect, useRef, useState } from 'react'
import EndpointCard from './EndpointCard'
import { getTopicIcon } from '../lib/icons'
-import { BASE_URL } from '../data/topics'
-// Strip the documented BASE_URL so fetches are same-origin and get
-// proxied by Vite (dev) or Express (prod), which injects the secret header.
-function toProxyPath(fullUrl) {
- if (fullUrl.startsWith(BASE_URL)) return fullUrl.slice(BASE_URL.length)
+import { LEGACY_BASE_URL } from '../data/topics'
+
+function toProxyPath(fullUrl, baseUrl) {
+ // Only proxy the legacy Hasura API (to inject the admin secret via server)
+ if (baseUrl === LEGACY_BASE_URL && fullUrl.startsWith(baseUrl)) {
+ return fullUrl.slice(baseUrl.length)
+ }
+ // Let the browser hit the new REST API directly (it supports CORS)
return fullUrl
}
@@ -21,8 +24,6 @@ export default function TopicView({ topic, searchQuery }) {
)
: topic.endpoints
- // Only one endpoint's response is visible at a time. Sending on a new
- // endpoint replaces the previous one (and cancels its in-flight fetch).
const [active, setActive] = useState(null)
const abortRef = useRef(null)
@@ -41,12 +42,28 @@ export default function TopicView({ topic, searchQuery }) {
setActive({ name: endpoint.name, result: null, loading: true })
const start = Date.now()
+
try {
- const res = await fetch(toProxyPath(composedUrl), {
+ const fetchOptions = {
method: endpoint.method,
headers: { 'Content-Type': 'application/json' },
signal: controller.signal
- })
+ }
+
+ if (['POST', 'PUT', 'PATCH'].includes(endpoint.method) && endpoint.body) {
+ if (typeof endpoint.body === 'string') {
+ try {
+ // Re-stringify in case it's a badly formatted JSON string, but mostly it's just raw string
+ fetchOptions.body = JSON.stringify(JSON.parse(endpoint.body))
+ } catch {
+ fetchOptions.body = endpoint.body
+ }
+ } else {
+ fetchOptions.body = JSON.stringify(endpoint.body)
+ }
+ }
+
+ const res = await fetch(toProxyPath(composedUrl, topic.baseUrl), fetchOptions)
const ms = Date.now() - start
const text = await res.text()
let body
@@ -71,23 +88,26 @@ export default function TopicView({ topic, searchQuery }) {
}
return (
-
-
-
-
-
-
{topic.name}
-
{topic.description}
-
- {filtered.length} endpoint{filtered.length === 1 ? '' : 's'}
-
+
+
+
{topic.name}
+
{topic.description}
+
+
+
+ {filtered.length} endpoint{filtered.length !== 1 ? 's' : ''}
{filtered.length === 0 ? (
-
+
No endpoints match "{searchQuery}".
) : (
@@ -95,8 +115,9 @@ export default function TopicView({ topic, searchQuery }) {
const isActive = active?.name === e.name
return (
{
if (secret) proxyReq.setHeader('x-hasura-admin-secret', secret)
})
}
+ },
+ '/live': {
+ target: 'https://fiesta.nearle.app',
+ changeOrigin: true,
+ secure: true,
+ configure: (proxy) => {
+ proxy.on('proxyReq', (proxyReq) => {
+ if (secret) proxyReq.setHeader('x-hasura-admin-secret', secret)
+ })
+ }
}
}
}