dataservices-api/doc/internal/internal_doc.md

Data Services API Internal documentation

• Existent services
• How to add a new service

Existent services

Available at cartodb_services.

• Google

  • Geocoding

• Here

  • Geocoding
  • Routing

How to add a new service

These are the steps that need to be followed when creating a new service in the API or updating an existent one.

Creating a new service function or editing an existent one

In this scenario, both client and server sides require to be edited/created.

• Update the interface file with the function addition or update

  • Interfaces are stored in client/renderer/interfaces
  • Interface YAML filenames follow the client versioning schema with the format interface-x.y.z.yaml.

• Update the renderer templates or script, if applicable

  • Renderer templates are stored in client/renderer/templates
  • The Renderer script (client/renderer/sql-template-renderer) generates SQL from the defined interfaces

• Generate a new subfolder version for sql and test folders to define the new functions and tests

  • TODO: Use symlinks to avoid file duplication between versions that don't update them
  • The client/sql folder contents are generated from the interfaces in the first step
  • Add or upgrade your SQL server functions
  • Create tests for the client and server functions -- at least, to check that those are created

• Generate the upgrade and downgrade files for the extension for both client and server

• Update the control files and the Makefiles to generate the complete SQL file for the new created version

  • These new version files (cdb_dataservices_client--X.Y.Z.sql and cdb_dataservices_server--X.Y.X.sql) must be pushed and frozen. You can add these to the .gitignore file.

• Update the public docs! ;-)

Updating an existing server side function

With no changes in client side.

Extension

• Generate a new subfolder version for sql and test folders to define the new functions and tests

  • TODO: Use symlinks to avoid file duplication between versions that don't update them
  • Add or upgrade your SQL server functions
    • For example, if a new street geocoder service is implemented, it will require a change in the main function (cdb_dataservices_server.cdb_geocode_street_point) and generate a new cdb_dataservices_server._cdb_newservice_geocode_street_point

• Generate the upgrade and downgrade files for the extension for the client

Python

• Add, if needed, new configuration elements

• Add the new functionality into the provider folder. If the provider is new, create a new folder(server/lib/python/cartodb_services/cartodb_services/{provider_name} and add the service (geocoder.py)

• Check the __init__.py files to follow the existent import conventions

• Add a new metric, if needed, at the corresponding service

• Update the package version in setup.py