API Design

API design is a large topic. We expect this page to grow over time.

OpenAPI

As you add API endpoints, please be conscious that we are exposing these endpoints as an OpenAPI document at /openapi (e.g. http://localhost:8080/openapi ). See Getting the OpenAPI Document in the API Guide for the user-facing documentation.

We’ve played around with validation tools such as https://quobix.com/vacuum/ and https://pb33f.io/doctor/ only to discover that our OpenAPI output is less than ideal, generating various warnings and errors.

You can prevent additional problems in our OpenAPI document by observing the following practices:

  • When creating a method name within an API class, make it unique.

If you are looking for a reference about the annotations used to generate the OpenAPI document, you can find it in the MicroProfile OpenAPI Specification.

Paths

A reminder from Wikipedia of what a path is:

        userinfo       host      port
        ┌──┴───┐ ┌──────┴──────┐ ┌┴┐
https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top
└─┬─┘   └─────────────┬────────────┘└───────┬───────┘ └────────────┬────────────┘ └┬┘
scheme          authority                  path                  query           fragment

Exposing Settings

Since Dataverse 4, database settings have been exposed via API at http://localhost:8080/api/admin/settings

(JVM options are probably available via the Payara REST API, but this is out of scope.)

Settings need to be exposed outside to API clients outside of /api/admin (which is typically restricted to localhost). Here are some guidelines to follow when exposing settings.

  • When you are exposing a database setting as-is:

    • Use /api/info/settings as the root path.

    • Append the name of the setting including the colon (e.g. :DatasetPublishPopupCustomText)

    • Final path example: /api/info/settings/:DatasetPublishPopupCustomText

  • If the absence of the database setting is filled in by a default value (e.g. :ZipDownloadLimit or :ApiTermsOfUse):

    • Use /api/info as the root path.

    • Append the setting but remove the colon and downcase the first character (e.g. zipDownloadLimit)

    • Final path example: /api/info/zipDownloadLimit

  • If the database setting you’re exposing make more sense outside of /api/info because there’s more context (e.g. :CustomDatasetSummaryFields):

    • Feel free to use a path outside of /api/info as the root path.

    • Given additional context, append a shortened name (e.g. /api/datasets/summaryFieldNames).

    • Final path example: /api/datasets/summaryFieldNames

  • If you need to expose a JVM option (MicroProfile setting) such as dataverse.api.allow-incomplete-metadata:

    • Use /api/info as the root path.

    • Append a meaningful name for the setting (e.g. incompleteMetadataViaApi).

    • Final path example: /api/info/incompleteMetadataViaApi