Skip to content

Latest commit

 

History

History
108 lines (84 loc) · 3.7 KB

README.md

File metadata and controls

108 lines (84 loc) · 3.7 KB
Raw

Flora

NPM version NPM downloads

Flora is a FLexible Open Rest API framework for Node.js.

Features

  • Resources in resources (recursive): fetch as much as possible in one request, without duplicating code
  • Lightweight (but powerful) field/sub-resource selection syntax: fetch exactly what you need in one request
  • Filter resources even by sub-resource-attributes: resolve inside database when possible, or return ID lists
  • Pluggable data sources: currently implemented: MySQL, MongoDB, Elasticsearch, Solr/Lucene
  • Combine multiple data sources: even on per-row-basis - "API-side-JOIN"
  • Highly optimized database queries: internal SQL parser to remove unselected fields and thus unreferenced LEFT JOINs
  • Locale: parameterize JOINs i.e. with a localeId - no need for database views which can't be parameterized
  • Handle all your special cases as good as possible: hooks and events for extending features

Server features

  • Node.js HTTP-Server and Cluster based implementation with self-monitoring process-management
  • Extremely verbose server-status - see everytime what the server is doing and what is hanging around in production
  • Straightforward logging/error handling - i.e. forward all errors to your favorite "error-monitoring-tool"
  • Updates in production with zero downtime - almost every part of code and config is replaceable without shutdown
  • Comfortable development-features - usual "code-change - F5 - see result"-workflow

Design goals

  • Generic implementation just for reading - offer helper for writing
  • Easy abstraction of complex and distributed database structures
  • Easy standard cases with minimal boilerplate code - special cases possible - "everywhere"
  • Flexibility, stability, performance, simplicity, transparency

Documentation

Examples

URL structure

Format

/path/to/resource/<id>
    ?action=<action>
    &select=xxx
    &filter=xxx
    &limit=10
    &page=1
    &width=100 (additional parameters)
    &height=100

Example URLs

  • GET /article/123 (retrieve article 123 as JSON)
  • GET /article/ (list of all articles)

Resource implementation

module.exports = (api) => ({
    actions: {
        retrieve: (request, response) => {
            return api.resourceProcessor.handle(request, response)
        },

        hello: () => {
            return Promise.resolve("Hello World");
            // return "Hello World"
            // Also, a Stream of Buffer can be returned
        },

        foo: {
            default: (request, response) => {
                // If "foo" was a function, only the default format was allowed.
                // This way you can define additional formats:
            },
            image: (request, response) => {
                // This is executed when /myresource/123.image?action=foo is called.
                // The behaviour of each format is not dictated by the framework.
                response.header('Content-Type', 'image/png');
                return … // Stream or Buffer
            }
        }
    }
});

Abstract definition

<?xml version="1.0" encoding="utf-8"?>
<resource primaryKey="id" xmlns:flora="urn:flora:options">
    <flora:dataSource type="mysql" database="contents" table="user"/>
    <id type="int"/>
    <firstname/>
    <lastname/>
</resource>

License

MIT