Common BB API endpoint design guidelines

Owned by Benjamin Balder Bach
Oct 01, 2023
1 min read

This draft was presented to the TC at a meeting for inspirational input.

(original text copied from a Google Presentation)

 

  • The root path for GovStack API

    • <base URL>

  • Building Block 

    • <base URL>/ ⇒ http://127.0.0.1:9000/consent/v1/

    • <base URL>/ ⇒ https://consent.utopia.gov/v1/

  • All APIs are classified into categories (nouns) - Our proposal is to add 4 well-known nouns: service, config, audit and notification

    • <base URL>/<category> - General format

    • <base URL>/service/ - Publicly available service for any application

    • <base URL>/config/ - Restricted by the network layer

    • <base URL>/audit/ - Restricted by the network layer

  • Each category may have an optional subcategory. E.g. Configurations/Policy 

    • <base URL>/<category>/<sub-category>

    • <base URL>/config/policy/

    • <base URL>/config/agreement/

  • Method name will specify the action (CRUDL operations)

    • POST <base URL>/config/agreement/

    • GET <base URL>/config/agreement/{agreement-id}

    • PUT <base URL>/config/agreement/

    • DELETE <base URL>/config/agreement/

    • GET <base URL>/config/agreements/

  • Proposed Endpoint Structure:

    • <base URL>/<category>/<sub-category>/<artifact>

    • CRUDL Operations: POST/GET/PUT/DELETE/GET

  • Consent BB Operations: (Proposed Endpoint Structure (Consent BB))