Skip to content

Commit fa5051f

Browse files
jitendra-webkuljitendra-webkul
authored
Merge pull request #20 from suraj-webkul/api-docs
added erp docs.
2 parents bf59c16 + 6635ead commit fa5051f

2 files changed

Lines changed: 296 additions & 0 deletions

File tree

‎.vitepress/routes/master.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,13 @@ const routes = [
215215
]
216216
}
217217
]
218+
},
219+
{
220+
text: 'AureusERP API',
221+
collapsed: false,
222+
items: [
223+
{ text: 'Introduction', link: '/master/api-reference/index' },
224+
]
218225
}
219226
]
220227

‎src/master/api-reference/index.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# REST API Reference
2+
3+
AureusERP exposes a full-featured REST API that gives you programmatic access to every module in the platform. Whether you are building third-party integrations, automating internal workflows, or syncing data with external systems, the API covers the complete lifecycle of your ERP data — from partners and inventory to purchases, employees, and beyond.
4+
5+
The API is documented and served interactively by [Scribe](https://scribe.knuckles.wtf/). You can browse every endpoint, inspect request and response schemas, and fire live requests without writing a single line of code.
6+
7+
> **💡 Interactive API Explorer**
8+
> Open **[/api/docs](/api/docs)** to explore every available endpoint with a built-in request builder.
9+
10+
---
11+
12+
## Base URL
13+
14+
All API endpoints are relative to your installation's base URL:
15+
16+
```
17+
https://{your-domain}/admin/api/v1
18+
```
19+
20+
Replace `{your-domain}` with the domain where AureusERP is installed (e.g., `erp.example.com`).
21+
22+
---
23+
24+
## API Versioning
25+
26+
The current API version is **v1**. The version is included in every endpoint path:
27+
28+
```
29+
/admin/api/v1/{resource}
30+
```
31+
---
32+
33+
## Authentication
34+
35+
The AureusERP API uses [Laravel Sanctum](https://laravel.com/docs/sanctum) for stateless, token-based authentication. You must obtain a Bearer token before making any protected request.
36+
37+
### Obtaining a Token
38+
39+
Send your credentials to the login endpoint:
40+
41+
```http
42+
POST /admin/api/v1/login
43+
Content-Type: application/json
44+
45+
{
46+
"email": "admin@example.com",
47+
"password": "your-password"
48+
}
49+
```
50+
51+
A successful response returns a token:
52+
53+
```json
54+
{
55+
"data": {
56+
"token": "1|abc123XYZ..."
57+
}
58+
}
59+
```
60+
61+
### Using the Token
62+
63+
Include the token as a `Bearer` header on every subsequent request:
64+
65+
```http
66+
GET /admin/api/v1/partners/partners/partners
67+
Authorization: Bearer {YOUR_AUTH_TOKEN}
68+
Accept: application/json
69+
```
70+
71+
### Revoking a Token
72+
73+
To log out and invalidate the current token:
74+
75+
```http
76+
POST /admin/api/v1/logout
77+
Authorization: Bearer {YOUR_AUTH_TOKEN}
78+
```
79+
80+
> **⚠️ Keep tokens secret**
81+
> Never expose your API token in client-side code, public repositories, or logs. Treat it like a password.
82+
83+
---
84+
85+
## Request Format
86+
87+
- All request bodies must be sent as **JSON** with the `Content-Type: application/json` header.
88+
- Always include `Accept: application/json` so error responses are returned as JSON rather than HTML.
89+
90+
```http
91+
POST /admin/api/v1/partners/partners
92+
Authorization: Bearer {YOUR_AUTH_TOKEN}
93+
Content-Type: application/json
94+
Accept: application/json
95+
96+
{
97+
"name": "Acme Corp",
98+
"email": "contact@acme.com"
99+
}
100+
```
101+
102+
---
103+
104+
## Response Format
105+
106+
All responses follow a consistent JSON envelope:
107+
108+
### Success — Single Resource
109+
110+
```json
111+
{
112+
"data": {
113+
"id": 1,
114+
"name": "Acme Corp",
115+
"email": "contact@acme.com",
116+
"created_at": "2026-03-17T10:00:00.000000Z",
117+
"updated_at": "2026-03-17T10:00:00.000000Z"
118+
}
119+
}
120+
```
121+
122+
### Success — Collection
123+
124+
```json
125+
{
126+
"data": [
127+
{
128+
"id": 1,
129+
"name": "Acme Corp"
130+
},
131+
{
132+
"id": 2,
133+
"name": "Beta Ltd"
134+
}
135+
],
136+
"links": {
137+
"first": "https://erp.example.com/admin/api/v1/partners/partners?page=1",
138+
"last": "https://erp.example.com/admin/api/v1/partners/partners?page=5",
139+
"prev": null,
140+
"next": "https://erp.example.com/admin/api/v1/partners/partners?page=2"
141+
},
142+
"meta": {
143+
"current_page": 1,
144+
"from": 1,
145+
"last_page": 5,
146+
"per_page": 15,
147+
"to": 15,
148+
"total": 72
149+
}
150+
}
151+
```
152+
153+
### Error
154+
155+
```json
156+
{
157+
"message": "The given data was invalid.",
158+
"errors": {
159+
"email": [
160+
"The email field is required."
161+
]
162+
}
163+
}
164+
```
165+
166+
---
167+
168+
## HTTP Status Codes
169+
170+
The API uses standard HTTP status codes to indicate the outcome of every request.
171+
172+
| Code | Meaning |
173+
|------|---------|
174+
| `200 OK` | Request succeeded. |
175+
| `201 Created` | Resource was successfully created. |
176+
| `204 No Content` | Request succeeded with no response body (e.g., DELETE). |
177+
| `400 Bad Request` | The request was malformed or missing required parameters. |
178+
| `401 Unauthorized` | Missing or invalid authentication token. |
179+
| `403 Forbidden` | The authenticated user lacks permission for this action. |
180+
| `404 Not Found` | The requested resource does not exist. |
181+
| `422 Unprocessable Entity` | Validation failed. Check the `errors` object in the response. |
182+
| `429 Too Many Requests` | Rate limit exceeded. Slow down and retry after the indicated period. |
183+
| `500 Internal Server Error` | An unexpected server-side error occurred. |
184+
185+
---
186+
187+
## Pagination
188+
189+
List endpoints return paginated results. Use the `page` and `per_page` query parameters to control pagination:
190+
191+
| Parameter | Default | Description |
192+
|-----------|---------|-------------|
193+
| `page` | `1` | The page number to retrieve. |
194+
| `per_page` | `15` | Number of records per page (max `100`). |
195+
196+
**Example:**
197+
198+
```http
199+
GET /admin/api/v1/partners/partners?page=2&per_page=25
200+
Authorization: Bearer {YOUR_AUTH_TOKEN}
201+
```
202+
203+
Pagination metadata is returned in the `meta` and `links` objects of every collection response (see [Response Format](#response-format) above).
204+
205+
---
206+
207+
## Filtering & Sorting
208+
209+
Most list endpoints support filtering by passing query parameters that match field names, as well as a `sort` parameter:
210+
211+
```http
212+
GET /admin/api/v1/partners/partners?filter[name]=Acme&sort=-created_at
213+
```
214+
215+
- Prefix a sort field with `-` for **descending** order.
216+
- Multiple sort fields can be comma-separated: `sort=name,-created_at`.
217+
218+
> **ℹ️ Note**
219+
> Refer to each resource's endpoint documentation in the [interactive explorer](/api/docs) for the full list of supported filters and sort fields.
220+
221+
---
222+
223+
## Regenerating API Documentation with Scribe
224+
225+
After making any changes to your API — such as adding new endpoints, updating request/response structures, or modifying permissions — you must regenerate the Scribe documentation so the interactive explorer stays in sync with your codebase.
226+
227+
### Regenerate Docs
228+
229+
Run the following Artisan command from your project root:
230+
231+
```bash
232+
php artisan scribe:generate
233+
```
234+
235+
This scans all your API routes, reads docblock annotations and FormRequest rules, and outputs a fresh set of documentation files.
236+
237+
### When to Regenerate
238+
239+
You should run `scribe:generate` whenever you:
240+
241+
- Add, rename, or remove an API endpoint.
242+
- Change request validation rules or response fields.
243+
- Update route middleware (e.g., permission or authentication guards).
244+
- Change the Scribe configuration file.
245+
246+
### Useful Flags
247+
248+
| Flag | Description |
249+
|------|-------------|
250+
| `--force` | Overwrite any manually edited docs without prompting. Cannot be combined with `--no-extraction`. |
251+
| `--no-extraction` | Skip extracting example responses from your app (useful in CI). Cannot be combined with `--force`. |
252+
| `--env=testing` | Run generation against a specific environment. |
253+
254+
> **⚠️ Note**
255+
> The `--force` and `--no-extraction` flags are mutually exclusive — Scribe will throw an error if you pass both at the same time. Choose one based on your use case.
256+
257+
**Example — force overwrite manually edited docs:**
258+
259+
```bash
260+
php artisan scribe:generate --force
261+
```
262+
263+
**Example — skip response extraction (useful in CI where the app may not be fully bootable):**
264+
265+
```bash
266+
php artisan scribe:generate --no-extraction
267+
```
268+
269+
> **💡 Tip**
270+
> Add `php artisan scribe:generate` to your deployment script or CI/CD pipeline so docs are always up to date after every release.
271+
272+
---
273+
274+
### Generate and Preview
275+
276+
After adding annotations, regenerate and review:
277+
278+
```bash
279+
# Regenerate the documentation
280+
php artisan scribe:generate
281+
282+
# Preview locally (docs are served at /api/docs by default)
283+
php artisan serve
284+
```
285+
286+
Open `http://localhost:8000/api/docs` to verify your new endpoints appear correctly.
287+
288+
> **⚠️ Important**
289+
> If your new endpoints are behind permission middleware, make sure the Scribe config includes the correct authentication headers so that example requests work in the interactive explorer.

0 commit comments

Comments
 (0)