API Design Guidelines chapter 11: 'info' object, 'servers' object and cleanup #214
Conversation
Removed figures as not clear, small edits
rartych
requested review from
shilpa-padgaonkar,
patrice-conil,
RubenBG7 and
PedroDiez
as code owners
Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
info object comments updated
|
@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. |
Example of servers object changed
rartych
dismissed stale reviews from patrice-conil and shilpa-padgaonkar
via
b8d4bf0
|
@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. |
| termsOfService: http://example.com/terms/ | ||
| # Contact information: name, email, URL | ||
| contact: | ||
| name: API Support |
There was a problem hiding this comment.
One doubt
which values are expected to be used in the APIs (I assume we will have to insert this information in every API so i think we could have some alignment regarding the value to be indicated to use the same approach among APIs or it is up to the WG the value to be provided).
Anycase, all of them (name, email, url) has to be indicated within the yaml, doesn`t?
name: support -> e.g. Blockchain Public Address Support
email: mail distribution list of the WG -> e.g. sp-bpa@lists.camaraproject.org
url: link to the WG site in CAMARA gtihub -> e.g. https://github.com/camaraproject/BlockchainPublicAddress
There was a problem hiding this comment.
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
@tanjadegroot @hdamker WDYT?
There was a problem hiding this comment.
I think we should include the information that is relevant for CAMARA in our specs, as each API provider will adapt our OAS spec to whatever template or format they use in their portals. title and version are the only required sub-sections for info section. If we decided to add the contact sub-section, I would fill it with contact details for CAMARA.
There was a problem hiding this comment.
I had added such contact subsection with Camara relevant details in the common.yaml as a part of the last release and would personally prefer this format as well.
There was a problem hiding this comment.
Following the discussion in Release Management: https://wiki.camaraproject.org/display/CAM/2024-06-04+Release+WG+Minutes and #214 (comment) I have removed contact and termsOfService from the info object and added some explanation.
See the changes: 2421afb.
|
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.md<#214 (comment)>:
+ # 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
@tanjadegroot<https://github.com/tanjadegroot> @hdamker<https://github.com/hdamker> WDYT?
—
Reply to this email directly, view it on GitHub<#214 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AU6LGAZ6ZBFV7UTVBSLRGYLZFVTWHAVCNFSM6AAAAABIHRMHLGVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDAOJVGU2DAOBQGU>.
You are receiving this because you were mentioned.Message ID: ***@***.******@***.***>>
|
|
Following the discussion in Release Management: https://wiki.camaraproject.org/display/CAM/2024-06-04+Release+WG+Minutes |
|
LGTM |
What type of PR is this?
Add one of the following kinds:
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
Additional documentation