Yocto API
This is a REST API for yocto
All http requests that are implemented by the yocto rest api :
- get : get an object or all object
- head : it 's the same that get, but return only the header
- post : add a new object
- put : a full update of object
- patch : update a property of object that is specified
- delete : delete an object
Important : to use yocto-api, you should use the midlleware cors for express : https://www.npmjs.com/package/cors
apidoc
Apidoc is a tool that permit to generate documentation of our REST API from comments https://github.com/apidoc/apidoc
You should add this main params in your package.json
SampleUrl is the main url of your api, this params will be use in each method you will define
"apidoc":
apidocGenerator
Apidoc generator is a little module that read each model file and create a comments file that will be used by apidoc
Example :
Using the api with a mongodb
'use strict'; var express = ; // Load expressvar bodyParser = ; // load bodyparservar mongoose = ; // Load the mongodb drivervar routes = ; // Load the apivar app = ; // Create app // connect to our databasemongoose; // configure app to use bodyParser()app;app; // set our portvar port = processenvPORT || 8080; //Initialise the API routerroutes; //Use the routerapp; // START THE SERVERapp;
model.json file
Each Model is defined in one json file.
In this file an object "apidoc" is also declared to generate the doc automatically
The structure of the json is as follows :
model object
A model have means a name, and one properties
Each properties can be a type, required or/and an array.
Example for firstaname that is a stirng required :
"model" :
Example for surname that is an optional String :
"model" :
Example for cart_id that is an optional array of ObjectId :
"model" :
Example for category_id that is an required array of ObjectId :
"model" :
Whole example :
apidoc object
An apidoc object can have lot of http methods, each method will create a new item in the doc
All this params are required :
- apiVersion : version of the api ( you can put multiple version of api)
- type : type of the request ( only : get, post, put, patch, delete, head)
- title : name of the method
- path : path of the method to test. We add path to sampleUrl declared in package.json. So your final url will be : 'sampleURL+path'
- apiPermission : the permission you should have to use it
- addDefaultParamFromModel : this option determine if you want add automatically params (thoose params are retrieve in model object), if it's false, none param will be added
- methoDescription : Description of the method
specificParam
This array of object define all param you want add and which are not present in model.
You can specify if it's required
"methods" :
apiSuccessExample param
This define the response that you will receive if your request is a success
They have default apiSuccess, you can call it by :
"methods" :
Or specify you own response :
"methods" :
apiErrorrExample param
This define the response that you will receive if your request is a an error
They have default apiErrorrExample, you can call it by :
"methods" :
Or specify you own response :
"methods" :
routes.json file
You can add multiple routes in the json file
You can add alias for the main Object of the url (it's useful for plurial)
By default all http request are implemented, you can exclude each request
You can specify the name of one parameter to retrieve in the url
You should specify the name of the model that you want use