API Design Guidelines chapter 11: 'info' object, 'servers' object and cleanup

[rartych]

What type of PR is this?

Add one of the following kinds:

• correction

What this PR does / why we need it:

The definitions of 'info' and 'servers` object were added to chapter 11. Other edits on API definition guidelines. I propose to remove the figures as they do not add value to the text.

Which issue(s) this PR fixes:

Fixes #199 Fixes #201

Special notes for reviewers:

Info object described in the same manner as here: https://swagger.io/docs/specification/api-general-info/

Changelog input

The definitions of 'info' and 'servers` object were added to chapter 11

Additional documentation

[shilpa-padgaonkar]

@patrice-conil , @PedroDiez and @RubenBG7 : Could you kindly review & approve this if all looks ok? we are trying to speed up reviews of at least the straightforward/simple PRs so that we are in time for the 0.4 release. Thanks in advance.

[shilpa-padgaonkar]

@PedroDiez or @RubenBG7 Could one of you kindly approve this PR (if you find no issues) so that we can proceed to merge? Thanks in advance.

[tanjadegroot]

Hi Rafal,

Yes that is indeed the assumption. It is a good idea to have that I the example and guidelines.

Cheers Tanja

From: Rafal Artych @.> Sent: Tuesday, June 4, 2024 9:25 AM To: camaraproject/Commonalities @.> Cc: Tanja De Groot (Nokia) @.>; Mention @.> Subject: Re: [camaraproject/Commonalities] API Design Guidelines chapter 11: 'info' object, 'servers' object and cleanup (PR #214)

@rartych commented on this pull request.

---

In documentation/API-design-guidelines.mdhttps://github.com/camaraproject/Commonalities/pull/214#discussion_r1625488344:

• title without "API" in it, e.g. "Number Verification"

• title: Number Verification

• description explaining the API, part of the API documentation

• 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 ...

• API version - Aligned to SemVer 2.0 according to CAMARA versioning guidelines

• version: 1.0.1

• Link to the page that describes the terms of service - to be replaced by the provider's terms

• termsOfService: http://example.com/terms/

• Contact information: name, email, URL

• contact:

• name: API Support

I think it is assumed that the contact information will be changed by each API Provider (Operator or Aggregator) when publishing API specification as the documentation for their service - possibly it should be explained in API Design Guidelines here in chapter 11. When yaml is hosted in CAMARA Github all contact info is in main README.md @tanjadegroothttps://github.com/tanjadegroot @hdamkerhttps://github.com/hdamker WDYT?

— Reply to this email directly, view it on GitHubhttps://github.com/camaraproject/Commonalities/pull/214#discussion_r1625488344, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AU6LGAZ6ZBFV7UTVBSLRGYLZFVTWHAVCNFSM6AAAAABIHRMHLGVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDAOJVGU2DAOBQGU. You are receiving this because you were mentioned.Message ID: @.**@.>>

[rartych]

Following the discussion in Release Management: https://wiki.camaraproject.org/display/CAM/2024-06-04+Release+WG+Minutes I have added x-camara-commonalities extension field to the info object.

[patrice-conil]

LGTM