Platform of Trust Platform Design Guide
Developer PortalAPI DocsOntology
  • Purpose and scope
  • Developer eXperience Strategy
  • Suggest changes
  • API Requests
    • Request validation
    • Response codes used
    • Error handling
  • General API guidelines
    • Performance
    • Documentation
    • Data models used
    • Use HATEOAS
    • Use HTTP Methods
    • Dates and time
    • Naming conventions
    • Pagination, partial response and sorting
    • API Testing
  • API Headers
    • Mandatory elements & behaviour
    • Rate limiting information
  • API Security
    • Authentication and authorization
    • SSL everywhere - all the time
  • API versioning guidelines
    • Versioning Rules
    • Breaking changes
    • Non-breaking changes example
    • Retirement process
    • Add new API to documentation
    • Add new endpoint
  • API Migration Policies
    • Deprecating API
    • Sunsetting API
    • Blackout Testing
    • Migration Email Template
    • API Blackout Test Email Template
    • API Deprecation Email
    • Deprecating an older API
  • Ontologies
    • About ontologies
    • Web Ontology Language, OWL
    • Ontology editor
    • Edit ontology
    • Add new subclass
    • Naming convention logic
    • Extending the ontology
  • Design Guideline
    • Colors
    • Typography
    • Grids and Space
    • Input forms - Text field
    • Input forms - Text area
    • Buttons
    • Checkbox
    • Radio buttons
    • Date picker
    • Form control - Single select
    • Toggle
    • Pagination
    • Status pills
    • Tables
    • Effects
    • Dialogues
Powered by GitBook
On this page
  • API Description formats
  • Getting started packages
  • 3-column documentation

Was this helpful?

  1. General API guidelines

Documentation

PreviousPerformanceNextData models used

Last updated 5 years ago

Was this helpful?

All APIs must be documented as if it would go public in the future. API documentation must be understandable, coherent and complete as is.

API Description formats

  • Internally we use RAML due to development pipeline and data model complexity and reuse.

  • For exposed APIs we publish format () in API Documentation.

    • For this purpose RAML spec (+ includes) must be in folder following the API name.

    • Example: Product API is in product-api folder in

Getting started packages

Each API must have getting started package which enables first great experience in under 3 minutes. The package can be implemented as part of the documentation described below or as separate section in Developer Portal.

Package shows how most common feature of the API is used. Package must contain runnable conde examples. Developer can choose whether to run code in browser (provided always) or in command-line in own machine. Result must be identical in both cases. On top of the code, API response with headers (and possible errors) must be visible to the user.

Getting started package utilizes sandbox provided by the PoT. Any code run in Getting started package is run only in snadbox environment, never in production environment.

3-column documentation

In API documentation we follow the path of most developer friendly documentation which is based on 3 columns. The left is reserved for TOC. Middle part is the description part (endpoint, function, feature). The part must contain also business reasons to apply API. The right column is for runnable code examples with selected programming languages.

The right part which contains code examples is utilizing sandbox environment provided for all registered developers. Developer can edit the API call (in the above example curl based call), push "execute" button and see the server response with headers below.

Open API Spec
v2
https://github.com/PlatformOfTrust/docs/tree/master/raml2markdown/src