This project will no be longer maintained cause of lack of interest, external support and external contribution. At the other side SAP, my main use case for this, developed CAP which solves my motivation for this repository.
I'm sorry for that. You can use this repository as is or feel free to fork and enhance it.
This project has been started to develop an OData server for node.js. There are already some solutions at npm. These did not fulfill our requirements which are
- Support for several backend systems (databases)
- Support for local file system database (light weight)
- Support for nearly the complete OData API
OData is a protocol for standardized access to RESTful webservices. It initially was developed by Microsoft as Open Source project. Not very much later SAP jumped onto the train. At the moment primarily Microsoft and SAP work on the specification under the hood of OASIS. Since it's early days in 2009 a lot of other companies have committed their strategy to OData or at least support OData. To name a few there are IBM, Salesforce, Red Hat, CA, Citrix. If you are totally new to OData this presentation might give you a quick inside into it.
In the meantime the current version of Odata is 4.0. We will try to support this version. But because we primarily are interested in using our server with the frontend framework SAPUI5/OpenUI5 which still works on V2 we will support version 2.0 at first.
The OData specification suggests to support Atom as well as JSON. One of these formats must be supported. We will probably only support the JSON format as it is much more lightweight and therefore easier to implement.
This project relies on and requires Loopback a very mature node.js framework for development of database independent node.js web applications. Our project extends this framework with the ability to expose it's data via OData. Loopback already exposes the data via a proprietary RESTful API. If you are fine with this just use it. But if you want to base your projects on standards use OData and our loopback add-on.
This component is not usable out of the box. You already need to have a loopback application. You can thent add this component to the existing application. Look here for details on installing and creating a loopback application.
Install the component like any other node package with npm
npm install n-odata-server --save
To use this loopback component you have to activate it in the file
server/component-config.json
of your project. Add the following lines to this file
"n-odata-server": {
"path": "/odata/*",
"odataversion": "2",
"useViaMiddleware": true
}
The line "odataversion": "2" means that the server works with OData V2. We highly recommend to use this version at the
moment.
Additionally you have to add route handling information to the file
server/middleware.json
An example of the configuration you see here:
{
"initial:before": {
"loopback#favicon": {}
},
"initial": {
"compression": {},
"cors": {
"params": {
"origin": true,
"credentials": true,
"maxAge": 86400
}
}
},
"session": {},
"auth": {},
"parse": {},
"routes": {
"n-odata-server#odata": {
"paths": [
"/odata/*"
]
},
"loopback#rest": {
"paths": [
"${restApiRoot}"
]
}
},
"files": {
"loopback#static": {
"params": "$!../client"
}
},
"final": {
"loopback#urlNotFound": {}
},
"final:after": {
"loopback#errorHandler": {}
}
}
With this configuration you can use the odata prefix to execute OData calls and the api prefix (loopback default) to execute standard restful json calls.
If you are not happy with the prefix odata you can of course use another one. Just exchange odata with your prefix in the paths array.
e.g. myservice. Then your requests to the odata service have to start with /myservice/.
See express documentation for more details on defining routes.
To fire your OData request simply start your server application with
node .
go to your browser and enter
http://0.0.0.0:3000/odata/
This will return the OData service document from which you can see which collections / entitysets are available in your OData server.
{
"@odata.context": "http://0.0.0.0:3000/odata/$metadata",
"value": [
{
"name": "people",
"url": "people"
}
]
}
In my case there is people entityset. When firing the URL
http://0.0.0.0:3000/odata/people
I get the data for this collection
{
"value": [
{
"firstname": "Helmut",
"lastname": "Tammen",
"id": 2
},
{
"firstname": "Franz",
"lastname": "Frosch",
"gender": "male",
"age": 65,
"id": 3
},
{
"firstname": "Mary",
"lastname": "Friday",
"gender": "female",
"age": 10,
"id": 4
},
{
"firstname": "Johannes",
"lastname": "Hamel",
"id": 8
}
]
}
Currently basic requests for the following http verbs are supported
GET: Get all records of an entityset or a single recordPOST: Create a new entry in your databaseDELETE: Delete an entry from your databasePATCH: Update an entry in your databaseMERGE: Update an entry in your database (to be OData V2.0 compatible)PUT: Update an entry in your database
If you encounter a lack in the implementation this is either not implemented yet or you found an error. In both cases you have the following opportunities
- fork the repo, fix the problem and raise a pull request so that we can take it over into the master branch of our project
- create an issue on Github
- wait until we came to the same error/lack and fixed it.
If you are not familiar with OData request have a look at the above mentioned OData resources.
Currently we don't support
- Batch requests. You have to configure your frontend to not using these. In SAPUI5 / OpenUI5 this can be done by setting a flag
- Atom / XML request. As mentioned above we only support JSON.
n-odata-server leverages the authentication and authorization mechanisms supplied by loopback. We have provided a wiki page to help you get started easily with this topic.
We use log4js for internal logging purposes.
Per default we log to the console and to a file named n_odata_server.log that is created in the root directory of your
development project.
The default logging configuration is quite verbose. If you don't want to see that much information you can adjust it.
Create a file named n_odata_server_log.json in the root directory of your project and configure your logging preferences.
See the log4js documentation for more details.
Following you see the default configuration that is used if the above mentioned file does not exist.
{
"appenders": [
{ "type": "console" },
{
"type": "file",
"filename": "n_odata_server.log",
"maxLogSize": 1048576
}
],
"replaceConsole": true,
"levels": {
"[all]": "TRACE"
}
}
To read more about the n-odata-server you should have a look at the wiki or you can have a look at this presentation for a not very technical overview
Have a look at our wiki page for tutorials that demonstrate the usage of n-odata-server.
Even though we are working hard we need some more time to have a version that supports most of the OData specification. Please stay tuned or contribute to the project if you want quicker results.
We have currently implemented some but not all OData functionality (see below). You should be able to use most of the basic CRUD operations on your data. We try to implement some more useful functionality as soon as possible. Additionally we make currently available functionality more stable every day.
To see what's implemented yet have a look at our release notes
If you want to contribute send us an email to h.tammen@tammen-it-solutions.de.
We are collaborating / communication via Slack and will invite you to our team as soon as we receive a request for contribution.
We manage our tasks via zube.io. We will also authorize you to our zube scrum board if you want to contribute to the project.
You can also have a look at the DEV_NOTES.md file to get more details about our development process.
This project is licensed under the MIT license. See the LICENSE file for more info.