Product Selector

Fusion 5.9
    Fusion 5.9

    Writing APIs

    Table of Contents
    This section was written for Springboard APIs. Fusion guidance may vary.

    APIs open up opportunities for users to interact with Lucidworks' products in ways that they cannot with the UI. Because the APIs allow customers to interact with data in ways that go beyond selecting items manually, there is rarely one typical use case for a given API. Therefore, we should avoid being prescriptive when describing how users should use the APIs.

    When documenting APIs, the docs site includes a general information reference page and an API specification.

    Use present tense for all descriptions in the API specifications.

    For API endpoints with many optional parameters, include a basic API request with the minimum necessary parameters and an advanced API request that includes all the parameters.

    Each API endpoint must include:

    • The URL

    • A description of the endpoint and what the user can do with it. You may provide a concrete example if a wide variety of use cases exist.

    • If there are similar API endpoints in the same API, what differentiates the two. An example of this is Search and Searchahead in the Springboard Connected Search API.

    Each API request body must include the following:

    • The parameters used in the request

    • Whether the parameter is required

    • The allowed values and format

    • A description of the parameter

    • The default value, if the user does not set a value

    Each API response must include:

    • The parameters in the response

    • Whether the parameter is always visible in the response (marked as Required in Stoplight)

    • The allowed values and format

    Build the API endpoint request and response specifications as schemas in Stoplight. Building as schemas supports documentation reuse with minimal effort.

    Resources