camaraproject / Commonalities

Repository to describe, develop, document and test the common guidelines and assets for CAMARA APIs
Apache License 2.0
11 stars 25 forks source link

Update example in API-design-guidelines.md #264

Open tanjadegroot opened 1 month ago

tanjadegroot commented 1 month ago

Problem description example should put the x-camara-commonalites field under the version field (section 11.1 Info object example) and above the description field.

Expected action

In the example (line ) move the version and x-camara-commonalities sections together, and before the description field (as this may be long)

this is a small fix - non blocking change for the next release candidate

info:
  # title without "API" in it, e.g. "Number Verification"
  title: Number Verification
  # API version - Aligned to SemVer 2.0 according to CAMARA versioning guidelines
  version: 1.0.1
  # CAMARA Commonalities version - x.y.z
  x-camara-commonalities: 0.4.0
  # description explaining the API, part of the API documentation 
  # includes text explaining how to fill the "Authorization and authentication" - see section 11.6
  description: |
    This API allows to verify that the provided mobile phone number is the one used in the device. It
    verifies that the user is using a device with the same mobile phone number as it is declared.
    ### Authorization and authentication
    CAMARA guidelines defines a set of authorization flows ...
  # Name of the license and a URL to the license description
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
hdamker commented 1 month ago

Currently the two lines are near to the server object which is a) another information which need to check in a release and b) essential information to use the API. Because of that I'm more in favor to keep the current order in the info object.