Skip to content

Latest commit

 

History

History
196 lines (159 loc) · 7.69 KB

README.md

File metadata and controls

196 lines (159 loc) · 7.69 KB
Raw

n-odata-server, The node OData server for the loopback framework

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

Current state of the project

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.

If you want to contribute send us an email to h.tammen@tammen-it-solutions.de. We are collaborating via a Slack Team and will invite you to this as soon as we receive a request for contribution. We manage our tasks via Trello. We will also authorize you to our Trello board if you want to contribute to the project.

We have currently implemented some very basic OData functionality (see below) that allows you to use some basic CRUD operations on your data. We try to implement some more useful functionality soon.

Release Notes

To see what's implemented yet have a look at our release notes

Background

OData

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.

OData versions

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.

OData formats

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.

Loopback

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.

Usage

Prerequisites

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.

Installation

Install the component like any other node package with npm

      npm install n-odata-server --save

Activation

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"
  }

If you are not happy with the prefix odata you can of course use another one. Just exchange odata with you prefix e.g. myservice. Then your requests to the odata service have to start with /myservice/. The line "odataversion": "2" means that the server works with OData V2. We highly recommend to use this version at the moment.

Firing OData requests

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
    }
  ]
}

Supported requests

Currently basic requests for the following http verbs are supported

  • GET: Get all records of an entityset or a single record
  • POST: Create a new entry in your database
  • DELETE: Delete an entry from your database
  • PATCH: Update an entry in your database
  • MERGE: 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.

OData restrictions

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.

Logging

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"
	}
}

Documentation

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

License

This project is licensed under the MIT license. See the LICENSE file for more info.