CRUD APIs & Routes

CRUD is an acronym that stands for Create, Read, Update, and Delete operations. These operations are fundamental to managing data within databases, extending their principles to the architectural design of REST APIs. As an API developer, you leverage the CRUD framework for giving the best API experience to your consumers.

Beeceptor supports CRUD routes to build JSON Rest APIs. This makes it easier to speed up the development, integration, and testing phases of software projects. This feature is particularly advantageous for projects at their inception, requiring CRUD capabilities for one or more entities. Here’s a brief overview of the CRUD operations on a given entity:

• Create: Adding new data or objects to the application.
• Read: Retrieving or fetching data from the application.
• Update: Modifying existing data within the application.
• Delete: Removing data from the application.

Configuring CRUD Routes

Beeceptor has designed its CRUD Routes to prioritize ease of use and efficiency. Follow these simple steps to begin with a new HTTP endpoint:

1. Open the CRUD API creator page at Beeceptor.

2. Enter the base path for the entity you're working with. E.g. for a Product entity, you could use /products or /api/products as your base path. You don't need to specify any trailing slashes.

3. Click on the Create CRUD API button. This action will redirect you to the newly created mock server, ready for use.

4. Beeceptor automatically generates the necessary JSON REST APIs. This base path serves as the foundation for all CRUD operations, which are distinguished by the HTTP method (GET, POST, PUT, DELETE) in the request.

5. The final step involves creating the JSON object you wish to add. Copy the API URLs and send a POST request to the appropriate CRUD path to create an object.

Existing Endpoint

You also have the flexibility to add CRUD routes to an existing mock server or endpoint. Simply navigate to the 'Mock Rules' section and select the Create New CRUD button.

REST APIs

Upon defining a CRUD route, several API endpoints are automatically generated. For instance, if you want to manage Products with a relative API base path of /api/products, specifying this single route will create the following APIs for managing the Product entity:

Purpose	HTTP Method	URL
Create a product	POST	/api/products
Retrieve all products	GET	/api/products
Retrieve one product	GET	/api/products/{id}
Update a product	PUT	/api/products/{id}
Partial update a product	PATCH	/api/products/{id}
Delete a product	DELETE	/api/products/{id}

Entity ID

The default identifier for objects is the id field. However, you can customize this route to use an alternative field name, such as entity_id, objectId, etc. If the identifier field is omitted in the create request (POST API request), a random 10-character record ID is generated by Beeceptor.

Data Bucket & JSON Objects

Beeceptor creates a unique data bucket for each endpoint, ensuring data partition at the endpoint level. Each endpoint can have multiple CRUD routes, and all the associated objects are stored within a single data bucket as JSON documents. This strategy not only facilitates data separation but also ensures a robust JSON handling experience, supporting complex data structures like nested objects, lists, and primitive data types.

CRUD Operations (e.g. Product)

The operations described below are with an assumption of managing a Product entity through the CRUD route /api/products.

Creating Objects

To create objects, send a valid JSON object through a POST HTTP request to the entity's base API path. The JSON object will be stored as provided, without any schema change or validation by Beeceptor. If the request payload lacks an id (identifier field), Beeceptor will automatically generate a unique identifier for the new object.

Parameter	Value
HTTP Method	POST
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products
Request payload	{   "price": 200,   "name": "Guitar" }
Response status code	200
Response payload	{   "id": "ff055a745667b8ffab51",   "price": 200,   "name": "Guitar" }

Retrieve All Objects

Use the GET API to fetch all objects stored for this route. The response will be a JSON Array containing a list of previously created objects. If no objects exist under this CRUD route, an empty array [] is returned, indicating a successful operation.

Parameter	Value
HTTP Method	GET
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products
Response status code	200
Response payload	[   { "id": "ff055a745667b8ffab51", "price": 300, "name": "Guitar" },   { "id": "83f1a6b994ba9b89e582", "price": 200, "name": "Violin" } ]

Retrieve An Object

Use this GET API to fetch a specific object by its identifier. The response will be a JSON object.

Parameter	Value
HTTP Method	GET
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products/{id}
Response status code	200 - Indicates success. 404 - Returned if an object with the specified ID cannot be found.
Response payload	{   "id": "83f1a6b994ba9b89e582",   "price": 200,   "name": "Violin" }

Update An Object (Whole)

Use the PUT API to modify an object. The JSON payload included in the HTTP request will overwrite the existing object associated with the specified ID. The identifier field will not be altered during this operation.

Parameter	Value
HTTP Method	PUT
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products/{id}
Request payload	{   "price": 500,   "name": "Guitar" }
Response status code	200
Response payload	{   "id": "ff055a745667b8ffab51",   "price": 500,   "name": "Guitar" }

Update An Object (Partial)

Use the PATCH API for partial updates or to modify specific fields of an object. The operation updates only the fields included in the HTTP request payload, leaving the rest of the object unchanged. For instance, in the request below, only the product's price is updated.

Parameter	Value
HTTP Method	PATCH
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products/{id}
Request payload	{   "price": 500 }
Response status code	200
Response payload	{   "id": "ff055a745667b8ffab51",   "price": 500 }

Delete An Object

Use this API to permanently remove an object from storage. Once deleted, the object cannot be recovered.

Parameter	Value
HTTP Method	DELETE
API URL	https://<endpoint-name>.proxy.beeceptor.com/api/products/{id}
Response status code	200 - Indicates success. 404 - Returned if an object with the specified ID cannot be found.
Response payload	{   "success": true }

CRUD Behavior

HTTP Status Codes

Beeceptor adheres to standard best practices for JSON REST APIs, utilizing HTTP status codes for errors and maintaining a consistent error structure. Here are a few examples of error responses:

A 400 HTTP status code is returned if the request payload contains malformed JSON:

{
    "error": {
        "code": "invalid_json_body",
        "message": "Invalid JSON in request body"
    }
}

A 404 HTTP status code is returned if an object with the given ID cannot be found:

{
    "error": {
        "code": "bad_request",
        "message": "resource not found"
    }
}

Storage Limits

CRUD routes are offered as a premium feature, with limits on the maximum number of objects per endpoint varying by subscription plan. The Individual plan accommodates up to 25 objects, whereas the Team plan supports up to 100 objects across all CRUD routes within an endpoint.

Subscription plan	Maximum number of objects allowed per endpoint
Free	10
Individual	25
Team	100
Scale	500
Enterprise	1000

Automatic Purging

When these limits are exceeded, Beeceptor initiates an automatic purging to free up space for new objects. This is done by tracking the last updated date, and the oldest records, based on creation or update, are automatically removed.

No Business Logic

This feature is particularly beneficial for storing and retrieving JSON objects while the APIs are under development to facilitate quicker integration and prototyping. These CRUD APIs operate without incorporating any business logic. For instance, two objects within an entity (CRUD path) may have varying schemas/structures, or missing the unique constraints on the id field, among other possibilities.

Higher Security

Beeceptor's mock servers are publicly accessible online, simplifying API simulation for testing and development. The CRUD routes defined here are also open for anyone to retrieve objects. To enhance security, consider enabling authentication via HTTP headers. For details, see enabling authentication for an endpoint.

Matching Mock Rules

Beeceptor offers the flexibility of combining mock rules with CRUD routes, enhancing your API development and testing capabilities. The CRUD routes in Beeceptor are designed to handle requests based on a specified request path prefix, effectively capturing all requests that match this prefix.

The mechanism for rule matching within an endpoint is determined by the order of priority of the rules. To ensure that CRUD routes are evaluated properly and not overshadowed by other mock rules, they should be prioritized at the top of the list. You can adjust the priority of a rule by dragging it to a higher position in the list.