> For the complete documentation index, see [llms.txt](https://itwithlyam.gitbook.io/orders-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://itwithlyam.gitbook.io/orders-api/master.md).
# Specification
**The Orders API is a RESTful API for users to track and check the status of IT with Lyam orders. This API can also add and resolve orders.**
## **Title**
**Orders API**
## **Problem**
**We are currently manually tracking orders, and clients should be able to submit orders 24/7.**
## **Solution**
**Build a RESTful API that a client (e.g. via Discord) can connect to.**
## **Implementation**
**We have decided to use the REpresentational State Transfer (REST) Protocol for the following reasons:**
* **The REST resource paradigm matches how we treat files in our Database**
* **We don’t need more than CRUD operations for now**
* **Event monitoring will come in the future**
## **Authentication**
**To check that API users have access to the chosen resource, we will create a page for the Orders API on IWL-L. This will create asecurely hashed Authorization token, which is then added to our Database. The API will check for the “Authorization” header during the request, and will send Error 401 Not Authorized if it does not exist and Error 403 Forbidden if the token does not have access to the selected resource.**
**Above: The Authorization flow**
## **Considerations**
**The currently planned V2 of IWL-L will include a “WebSocket Gateway”, where there will be events interacting with the Orders API. These may include “ORDER\_CREATE”, “ORDER\_RESOLVE” and “ORDER\_DELETE”. However, this is long in the future. We might also switch to OAuth 2.0 Authentication, but IWL-L is an easy in-house solution. Using GraphQL for some operations also seems logical, but it would be optional.**
## **REST Endpoints**
| **URI** | **Inputs** | **Outputs** | **Scope** | **Added yet** |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ------------------ |
| GET
/orders
| Required: N/A
Optional:
Limit (int)
default 100, max 1000
last\_updated\_after (timestamp)
default null
| 200 OK
Array of Orders
\[
{
“id”: orderId,
“name”: string,
“timestamp”: timestamp,
“last\_updated”: timestamp,
“payment”: int,
“is\_deleted”: boolean,
“notes”: array of Notes,
“resolved”: string
}
]
| **moderator** | **Yes** |
| GET
/orders/:id
| **N/A** | 200 OK
Order Object
| **read+** | **Yes** |
| PATCH
/orders/:id
| Updatable fields:
name (string)
payment (int)
name (string)
resolved (string)
| 202 Accepted
Order Object
| **write+** | **In Development** |
| POST
/orders
| Required:
name (string)
payment (int)
| 200 Created
Order Object
| **write** | **No** |
| **DELETE /orders/:id** | Required:
resolved (string)
| **204 No Response** | **moderator** | **No** |
| POST
/orders/notes
| Required:
notes (array of Notes)
| **200 Created** | **developer** | **No** |
\
**Errors**
----------------
| **HTTP Code** | **Verbose error** | **Description** |
| ------------- | ----------------------- | --------------------------------------------------------- |
| **200-299** | **SUCCESS** | **Success** |
| **304** | **NO\_CONTENT** | **No content was returned** |
| **400** | **BAD\_REQUEST** | **We received an improper request** |
| **401** | **NOT\_AUTHORIZED** | **The Authorization header was missing** |
| **403** | **FORBIDDEN** | **You do not have access to the resource** |
| **404** | **NOT\_FOUND** | **The resource was not found** |
| **429** | **TOO\_MANY\_REQUESTS** | **Rate limited** |
| **500+** | **INTERNAL\_ERROR** | **There was an error in our system! Please report this.** |
## **Rate limiting**
**Our API allows up to 25 requests in 3 minutes. Any violations will result in 429 Too Many Requests. All violations are logged, and repeated violations can escalate to a token or IP ban. This should be more than enough time, since each request takes a couple of seconds to resolve.**
| **Name** | **Description** | **Example** |
| ------------------------- | -------------------------------- | ----------- |
| **X-RateLimit-Limit** | **Request limit** | **25** |
| **X-RateLimit-Remaining** | **Remaining available requests** | **24** |
| **X-RateLimit-Reset** | **Seconds to rate limit reset** | **60** |
## **Feedback plan**
**The Orders API will be released to Beta Testers along with IWL-L, as they are built together. Beta Testers will be asked via a Google Form for feedback.**
{% hint style="info" %}
**See this (and more) at** [**https://spec.itwithlyam.co.uk**](https://spec.itwithlyam.co.uk)
{% endhint %}