Skip to content

Latest commit

 

History

History
43 lines (26 loc) · 3.46 KB

ARCHITECTURE.md

File metadata and controls

43 lines (26 loc) · 3.46 KB
Raw

Architecture

The handler for each route from the OSM API is a separate file under /routes. The handler is only responsible for turning the XML request into the an internal API call, and for turning the results of that call into properly formatted XML and sending it to the response. The internal API calls in /api handle the logic of getting or putting the correct data in osm-p2p-db. We don't use any higher-level frameworks like Express, Hapi or Koa, we just use the minimalist router routes to match URL paths and call the appropriate handler function, which expects vanilla node.js request and response objects - frameworks like Express wrap these objects with additional properties and methods, but that should not affect osm-p2p-server. You are free to wrap osm-p2p-server in whichever framework you prefer to add authentication or more advanced routing.

Table of Contents

Routes

Each route handler under /routes is called by the router with the following arguments:

  • req - an http.IncomingMessage
  • res - an http.ServerResponse
  • api - an object of internal API methods wrapping the osm-p2p-db instance.
  • params - an object of matched route parameters. For example, for path /node/5, params would be {type: 'node', id: '5'}
  • next - a function to pass to the next matched route. Call with an Error object to pass control to the error handler.

The REST API currently only speaks XML, like the OSM API, but it would be relatively easy to make it speak JSON by modifying these route handler functions - PRs welcome! Internally all OSM entities are represented as objects matching the OSM JSON output format of the Overpass API. osm2json and obj2osm handle the transformation from XML to objects and vice-versa.

Internal API

Each method of the internal API is a separate file under /api. These are higher-level wrappers for the low-level osm-p2p-db API and may eventual move into their own module. These API methods expect entities as objects matching the OSM JSON format. Some methods, like getMap() and getChanges() implement both a streaming interface and a regular callback pattern.

Custom Errors

To keep errors more consistent we create custom errors which are defined in /errors/errors.json. These should match the errors defined in the OSM API specification as closely as possible.

Tests

Tests use tape. Integration tests sit directly under /test with unit tests in subfolders matching the project layout. Right now test coverage is not 100% and PRs are welcome.

Code Style

All code follows JS Standard Style.