51 lines
1.9 KiB
ReStructuredText
51 lines
1.9 KiB
ReStructuredText
**************
|
|
Managing Specs
|
|
**************
|
|
|
|
Here we cover several strategies for dealing with larger projects composed of
|
|
many specs, routes, and user-defined types.
|
|
|
|
Using Namespaces
|
|
================
|
|
|
|
Whenever possible, group related routes and their associated data types into
|
|
namespaces. This organizes your API into logical groups.
|
|
|
|
Code backends should translate your namespaces into logical groups in the
|
|
target language. For example, the Python backend creates a separate Python
|
|
module for each namespace.
|
|
|
|
Splitting a Namespace Across Files
|
|
==================================
|
|
|
|
If a spec is growing large and unwieldy with thousands of lines, it might make
|
|
sense to split the namespace across multiple spec files.
|
|
|
|
All you need to do is create multiple ``.stone`` files with the same
|
|
`Namespace <lang_ref.rst#namespace>`_ definition. Code backends cannot
|
|
distinguish between spec files--only namespaces--so no code will be affected.
|
|
|
|
When splitting a namespace across multiple spec files, each file should use the
|
|
namespace name as a prefix of its filename.
|
|
|
|
The ``stone`` command-line interface makes it easy to specify multiple
|
|
specs::
|
|
|
|
$ stone python spec1.stone spec2.stone spec3.stone output/
|
|
$ stone python *.stone output/
|
|
|
|
Separating Public and Private Routes
|
|
====================================
|
|
|
|
Most services have a set of public routes that they publish for external
|
|
developers, as well as a set of private routes that are intended to only be
|
|
used internally by first-party apps.
|
|
|
|
To use Stone for both public and private routes, we recommend splitting specs
|
|
into ``{namespace}_public.stone`` and ``{namespace}_private.stone`` files. You
|
|
may choose to simply use ``{namespace}.stone`` to represent the public spec.
|
|
|
|
When publishing your API to third-party developers, you can simply include the
|
|
public spec file. When generating code for internal use, you can use both the
|
|
public and private spec files.
|