Restalize Template
This is a helper module for Restalize REST API generator. It serves as a template for the REST API project generated by Restalize.
Cloning and using the repo
Since this package belongs to a monorepo, cloning it alone means you need to use git filter-branch
to remove unnecessary files:
git clone https://github.com/kennasoft/restalize.git
git filter-branch --subdirectory-filter packages/restalize-template
If you already have your typeorm entities/models defined (see examples at tests/lib/entities), you can throw them in the directory server/lib/entities, and you have yourself a basic CRUD (Create, Read, Update, Delete) REST API complete with Open API 2.0 (swagger) documentation. Remember to specify your own typeorm database connection details in a .env file (see .env.sample
).
When you start the express or hapi server using yarn dev
or yarn dev:hapi
commands respectively, it generates 7 different API routes for each entity/model. For example, if you have an entity called Pet
, you'll get the following endpoints:
- GET /api/Pets # fetch a list of Pets based on request query params
- GET /api/Pets/:id # fetch a single Pet based on the id path param
- POST /api/Pets # create a single Pet based on JSON payload in request body
- PUT /api/Pets # update a Pet or multiple Pets based on condition found in request payload
- PUT /api/Pets/:id # update the Pet with id matching the id in request path using the update fields in the request body
- DELETE /api/Pets # delete multiple Pets based on condition found in request payload
- DELETE /api/Pets/:id # delete the Pet with id matching the id in request path
Apart from the routes listed above, you also get the /api
route which lands on a swagger UI page listing all available endpoints
- GET /api # display the OpenApi UI to see all available endpoints
Which will give a page like this:
The GET request has some useful querying, sorting, and filtering features that can be used on the endpoint, which we'll look into in this document.
How to use the API:
1. Getting all Entity instances
You can fetch all rows paginated (20 rows per page) by doing a simple get request to the /api/Pets endpoint without any query parameters. E.g. running the command below in a terminal
curl -X GET http://localhost:3000/api/Pets
will result in the following output:
{
"status": "success",
"data": {
"total": 5,
"subtotal": 5,
"currentPage": 1,
"totalPages": 1,
"rows": [
{
"name": "FuzzyCat",
"photoUrls": [
"http://loremflickr.com/g/320/240/cat",
"http://loremflickr.com/320/240/cat"
],
"status": "available"
},
{
"name": "NaughtyDog",
"photoUrls": [
"http://loremflickr.com/g/320/240/dog",
"http://loremflickr.com/320/240/dog"
],
"status": "available"
},
{
"name": "Spotty",
"photoUrls": [
"http://loremflickr.com/g/320/240/leopard",
"http://loremflickr.com/320/240/leopard"
],
"status": "available"
},
{
"name": "King Kong",
"photoUrls": [
"http://www.sciencedump.com/sites/default/files/field/teaserimage/gorilla.jpg",
"http://www.kidzone.ws/ANIMALS/gorillas/gorilla.jpg",
"http://i.dailymail.co.uk/i/pix/2014/04/14/article-2604010-1D117C4D00000578-291_634x782.jpg",
"http://i4.mirror.co.uk/incoming/article8084087.ece/ALTERNATES/s615/MAIN-Dublin-zoo-gorilla-dies-after-short-illness.jpg"
],
"status": "available"
},
{
"name": "Tyrannosaurus Rex",
"photoUrls": [
"http://vignette2.wikia.nocookie.net/jurassicpark/images/5/57/Jurassic-world-stomp-strike-tyrannosaurus-rex-1.jpg/revision/latest?cb=20150213174835",
"http://orig03.deviantart.net/f652/f/2014/331/5/7/jurassic_world__tyrannosaurus_rex_by_sonichedgehog2-d87wp3n.png",
"http://www.abc.net.au/news/image/7251586-3x2-940x627.jpg",
"http://www.sideshowtoy.com/assets/products/200209-t-rex-the-tyrant-king/lg/200209-t-rex-the-tyrant-king-003.jpg"
],
"status": "unavailable"
}
]
}
}
2. Getting entities with simple query parameters
Beyond a simple GET, you can also fetch a list of entities matching criteria in the GET request querystring. For example, to get entities with the name field equal to FuzzyCat, we can do:
curl -X GET http://localhost:3000/api/Pets?name=FuzzyCat
which results in an SQL query to the backing store similar to the following
SELECT * FROM pet WHERE name='FuzzyCat';
We can also fetch entities using multiple criteria, e.g.
curl -X GET http://localhost:3000/api/Pets?name=FuzzyCat&status=available
which results in an SQL query to the backing store similar to
SELECT * FROM pet WHERE name='FuzzyCat' AND status='available';
3. Getting entities with more complex query parameters
The API also offers more advanced querying using a special set of operators described in the table below:
3.1 REST API operators
The general syntax for using operators in the GET request is
/api/PluralEntityName?[fieldName].[operator]=value
or when you apply the not
operator
/api/PluralEntityName?[fieldName].not.[operator]=value
3.2 REST API response modifiers
Beyond the operators that can be passed in the request querystring, you can also pass response modifiers, to sort, paginate, and select fields. Below is a list of the modifiers available to your API
Here is a sample request to get all Pets of the category with id=1, showing 1 item per page:
curl -X GET http://localhost:3000/api/Pets?category=1&_page_=1&_pageSize_=1&_select_=id,name,status,category,tags