Provider

In your Koop server file, the provider must be registered with the Koop instance before the it begins listening.

const Koop = require('@koopjs/koop-core')
const koop = new Koop()
const provider = require('<provider-npm-package or local-path>')
koop.register(provider, { /* provider options */ })
koop.server.listen(80)
Figure 1. Example of a Koop instance registering a provider.

Options

The provider registration options are summarized below, followed by detailed descriptions and usage examples:

name type description
name String Namespace replacement for the registered provider
before Function A transformation function that is executed before the provider’s getData function and can be used to modify the request object
after Function A transformation function that is executed after the provider’s getData function and can be used to modify the request object or the GeoJSON generated by the provider
routePrefix String A prefix for all provider routes

name

Use the name option to change the namespace of the provider routes:

const koop = new Koop()
const socrata = require('@koopjs/provider-socrata')
koop.register(socrata, { name: 'my-provider' })
Figure 2. Use the name option to change the namespace of a registered provider.

In figure 2, we are able to use the name option to register the same Socrata provider with the namespace my-provider. It will generate routes like /my-provider/:host/:id/FeatureServer/:layer/:method rather than the default /koop-provider-socrata/:host/:id/FeatureServer/:layer/:method. Custom namespacing can be useful if you want to register multiple providers of the same type, but with different transformation functions.

before

The before option allows you to add a “transformation” function to the provider call stack. It is useful if you want to use an existing provider from the npm registry, but want to customize its functionality. A before transform can execute your block of code before the provider’s getData method and can modify the Express request object.

Arguments

name type description
request Object An Express request object. See the Express documentation for more details.
callback Function An error-only callback function. It functions similiar to the Express next function. If no error, fire the callback with no arguments.

An example of using the before transform might be to reject requests for certain resources:

const koop = new Koop()
const socrata = require('@koopjs/provider-socrata')

koop.register(socrata, {
  before: (request, callback) => {
    
    const { params: { id } } = request

    // Reject any requests with id 'xyz'
    if (id === 'xyz') {
      const error = new Error('Forbidden')
      error.code = 403
      return callback(error)
    }
    callback()
  }
})
Figure 3. Example of using a before function to reject specific requests.

The before function can also be used to modify the request object. In the example below, we use the before function, to set/replace the value of resultRecordCount. This is useful because it allows you to modify the parameters used by your provider’s getData method without having to fork the repository and change any of its code:

const koop = new Koop()
const socrata = require('@koopjs/provider-socrata')

koop.register(socrata, {
  before: (request, callback) => {

    const { query: { resultRecordCount } } = request

    request.query.resultRecordCount = 10

    callback()
  }
})
Figure 4. Example of using an before function to alter the value of the resultRecordCount parameter.

after

The after option allows you to add a “transformation” function to the provider call stack. It is useful if you want to use an existing provider from the npm registry, but want to customize its functionality. An after transform can execute your block of code after the provider’s getData. It can modify the Express request object and / or the provider-generated GeoJSON object.

Arguments

name type description
request Object An Express request object. Contains route and query parameters for use in building the URL to the remote API. See the Express documentation for more details.
geojson Object The GeoJSON generated by the provider’s getData method
callback Function An error-first callback function. If no error, the second argument should be the geojson object.

An example use of the after function is setting values on the GeoJSON generate by the provider. For example, you can change the value of the crs property with the following after function:

const koop = new Koop()
const reproject = require('reproject')
const proj4 = require('proj4')
const github = require('@koopjs/provider-github')

koop.register(github, {
  after: (request, geojson, callback) => {

    geojson.crs = {
      type: 'name',
      properties: {
        name: "urn:ogc:def:crs:OGC:1.3:EPSG::2285"
        }
      }

    callback(null, geojson)
  }
})
Figure 5. Example of using an after function to add a crs field to the GeoJSON.

Note that like the before function, the after option can also modify the request object. In the following example, the inputCrs query parameter is set in the after function.

const koop = new Koop()
const reproject = require('reproject')
const proj4 = require('proj4')
const github = require('@koopjs/provider-github')

koop.register(github, {
  after: (request, geojson, callback) => {

    request.query.inputCrs = 2285

    callback(null, geojson)
  }
})
Figure 6. Example of using an after function to add an `inputCrs` property to the request object.

routePrefix

If needed, you can add a prefix to all of a registered provider’s routes. For example, if you wanted the fragment /api/v1 prepended to you github provider routes you could register the provider like this:

const provider = require('@koopjs/provider-github')
koop.register(provider, { routePrefix: '/api/v1' })

which results in routes like:

/api/v1/github/:id/FeatureServer

Plugin registration order

The order in which you register plugins can affect functionality. The key points are:

  • Provider data will only be accessible from output-plugin routes if the provider is registered after the output-plugin
  • Provider data will only be secured by an authorization plugin if the provider is registered after the authorization-plugin.

You can therefore micro-manage provider accessibility by adjusting the registration order of various plugins.

Koop CLI

If you are using the Koop CLI, adding a new provider to you Koop application is easy:

> koop add provider <provider-plugin-package-or-path>

See the Koop CLI documentation for additional options and details.


Improve this page