New guidelines documents by rartych · Pull Request #430 · camaraproject/Commonalities

rartych · 2025-03-17T14:47:15Z

What type of PR is this?

documentation

What this PR does / why we need it:

Working documents for cleanup of API Design Guidelines.
The initial issue: #306

CAMARA API Design Guide.md - proposed new guidelines document based on structure defined in Create Camara-OAS-Sections-Guidelines.md #317
CAMARA API Event Subscription and Notification.md - proposed separate document for using subscriptions
API-design-guidelines-remainder.md - the content of current API Design Guidelines not transferred to the new documents
CAMARA API Design Guide AI suggestions.md - improvements to the new guidelines document proposed by Large Language Model - the diff view can be seen with this link. Be aware: AI hallucinations possible!

Which issue(s) this PR fixes:

Fixes

Does this PR introduce a breaking change?

Yes
No

Special notes for reviewers:

For further discussion: initially we need to verify if all requirements are covered by new documents.

…_LLM.md

OpenAPI version and reserved words transferred to the new document

replace Camara with CAMARA where possible

POST or GET transferred to the new document Content-type header transferred to the new document

ToC updated

…s.md

…n Guide.md

… Notification.md

…suggestions.md

rartych · 2025-03-19T17:47:07Z

Filenames were updated to be more descriptive - PR description explains what is the purpose for each file.

tlohmar · 2025-03-31T15:36:20Z

documentation/CAMARA API Design Guide.md

+  - `GET /users?creationDate.gte=2020-01-01T00:00:00&creationDate.lte=2021-12-31T23:59:59`
+    - Search for users created between 2020 and 2021
+
+## Security


Adding Section Numbers could increase readability.

tlohmar · 2025-03-31T15:38:54Z

documentation/CAMARA API Design Guide.md

+
+1. **Simple Management**. 
+   Securing only the APIs that need to be secure. Any time the more complex solution is made "unnecessarily", it is also likely to leave a hole. 
+2. **HTTPs must be always used**. 


Could make sense to say "for production installation" (i.e. separate staging / testing installations)

tlohmar · 2025-03-31T15:39:57Z

documentation/CAMARA API Design Guide.md

+   Securing only the APIs that need to be secure. Any time the more complex solution is made "unnecessarily", it is also likely to leave a hole. 
+2. **HTTPs must be always used**. 
+   TLS ensures the confidentiality of the transported data and that the server's hostname matches the server's SSL certificate.
+   - If HTTP 2 is used to improve performance, you can even send multiple requests over a single connection, this way you will avoid the complete overhead of TCP and SSL on later requests.


Note, usage of HTTP1.1 persistent connections allows also sending multiple requests over the same TCP connection.

tlohmar · 2025-03-31T15:42:32Z

documentation/CAMARA API Design Guide.md

+### Security definition
+
+In general, all APIs must be secured to ensure who has access to what and for what purpose.
+CAMARA uses OIDC and CIBA for authentication and consent collection and to determine whether the user has,


No OAuth Client Credentials?

tlohmar · 2025-03-31T15:44:19Z

documentation/CAMARA API Design Guide.md

+CAMARA uses OIDC and CIBA for authentication and consent collection and to determine whether the user has,
+e.g. opted out of some API access.
+
+The [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose) defines that a single purpose is encoded in the list of scope values. The purpose values are defined by W3C Data Privacy Vocabulary as indicated in the [Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose-as-a-scope).


Always?
What about APIs, where OAuth Client Credentials (i.e. no relation to personal data) can be used?

A purpose is only needed when accessing personal data.

tlohmar · 2025-03-31T15:46:24Z

documentation/CAMARA API Design Guide.md

+The name `openId` must be same as defined in the components.securitySchemes section.
+
+
+### Mandatory template for `info.description` in CAMARA API specs


Is this template applicable to 3-legged and also 2-legged tokens (aka also for Client Credential cases)?

tlohmar · 2025-03-31T15:47:58Z

documentation/CAMARA API Design Guide.md

+
+Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object).
+
+The following is an example of how to use the `openId` security scheme defined above as described in [Use of security property](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-security-property):


Isnt it better to have the example in the Security & Interoperability Guideline?

tlohmar · 2025-03-31T15:51:00Z

documentation/CAMARA API Design Guide.md

+
+Using the GET operation to pass sensitive data potentially embeds this information in the URL
+if contained in query or path parameters.
+For example, this information can remain in browser history, could be visible to anyone who can read the URL,


...could be visible to anyone who can read the URL

When HTTPS / TLS is used, only authorized people can read the URLs, e.g. people with an admin password on the server.

Suggested change

For example, this information can remain in browser history, could be visible to anyone who can read the URL,

For example, this information can remain in browser history and could be visible to anyone who can read the browser history,

tlohmar · 2025-03-31T15:52:35Z

documentation/CAMARA API Design Guide.md

+Using the GET operation to pass sensitive data potentially embeds this information in the URL
+if contained in query or path parameters.
+For example, this information can remain in browser history, could be visible to anyone who can read the URL,
+or could be logged by elements along the route such as gateways and load balancers.


well, also headers and the body can be logged. However, logs are often limited to most essential info.

And, access to log files is often limited to admins, i.e. privileged users.

rartych · 2025-04-03T14:38:53Z

@tlohmar Thanks for your comments, some of them can be addressed by ICM, some of them can be subject to separate PR when we agree on the new document structure and content directly transferred from current guidelines document.

PedroDiez

As a suggestion would recommend to user "hyphens" instead of "spaces" for file names

documentation/CAMARA API Design Guide.md

documentation/CAMARA API Event Subscription and Notification.md

documentation/API-design-guidelines-remainder.md

Some additional sections from chapter 3, 4, 11 transferred to the new document

New version with changed struscture, added content and ToC

…de.md file name without spaces

tlohmar · 2025-04-07T17:42:59Z

documentation/CAMARA-API-Design-Guide.md

+
+#### 5.5.1. api-name
+
+`api-name` is what is specified as the base path, prior to the API version, in the `servers[*].url` property.


Is it ok, when the api-name string includes a forward slash (e.g. /location/verification/v0) (as /api-name/api-version)?

When not, I suggest to add a statement, that the forward slash character is not allowed.

api-name in the example is location-verification and it is stated below it should be "kebab-case string" so other special characters beside "dash" are not allowed.

…o CAMARA-API-Event-Subscription-and-Notification.md Formated and restructured, ToC added

rartych · 2025-04-08T13:40:03Z

The work will continue in PR #441

rartych added 21 commits March 12, 2025 08:56

Add files via upload

26c8c40

Delete documentation/API_DG_new.md

3065ea0

Delete documentation/API_DG_rest.md

4d55415

Add files via upload

dfdca79

Add files via upload

cdee0b5

Update and rename API_DG_rest.md to documentation/API_DG_rest.md

b0e26ef

Update and rename CAMARA_API_DG_LLM.md to documentation/CAMARA_API_DG…

7059662

…_LLM.md

Update CAMARA_API_DG_new.md

306c5a9

Update CAMARA_API_DG_LLM.md

a36a46f

Update API_DG_rest.md

6ddbab2

OpenAPI version and reserved words transferred to the new document

Update CAMARA_API_DG_new.md

f2327c5

OpenAPI version and reserved words transferred to the new document

Update CAMARA_API_DG_new.md

18497dd

replace Camara with CAMARA where possible

Update API_DG_rest.md

9c2eb11

POST or GET transferred to the new document Content-type header transferred to the new document

Update CAMARA_API_DG_new.md

26114f2

POST or GET transferred to the new document Content-type header transferred to the new document

Update CAMARA_API_DG_new.md

c5188da

ToC updated

Update and rename CAMARA_API_DG_new.md to CAMARA API Design Guideline…

6efee39

…s.md

Update and rename CAMARA API Design Guidelines.md to CAMARA API Desig…

f5c4e83

…n Guide.md

Update CAMARA API Design Guide.md

b422d48

Update and rename API_DG_rest.md to API-design-guidelines-remainder.md

14fc667

Update and rename Event_Guide.md to CAMARA API Event Subscription and…

a44c990

… Notification.md

Update and rename CAMARA_API_DG_LLM.md to CAMARA API Design Guide AI …

ebad939

…suggestions.md

rartych added documentation Improvements or additions to documentation Fall25 labels Mar 21, 2025

rartych added this to the Fall25-M1 milestone Mar 21, 2025

rartych mentioned this pull request Mar 31, 2025

Consistency around usage OAuth Client Credentials grant flow #434

Closed

tlohmar reviewed Mar 31, 2025

View reviewed changes

PedroDiez reviewed Apr 3, 2025

View reviewed changes

rartych added 3 commits April 7, 2025 18:44

Update API-design-guidelines-remainder.md

3096c24

Some additional sections from chapter 3, 4, 11 transferred to the new document

Update CAMARA API Design Guide.md

9d8677d

New version with changed struscture, added content and ToC

Update and rename CAMARA API Design Guide.md to CAMARA-API-Design-Gui…

759338d

…de.md file name without spaces

tlohmar reviewed Apr 7, 2025

View reviewed changes

Update and rename CAMARA API Event Subscription and Notification.md t…

7f6d778

…o CAMARA-API-Event-Subscription-and-Notification.md Formated and restructured, ToC added

rartych mentioned this pull request Apr 8, 2025

CAMARA API Design Guide document #441

Merged

2 tasks

rartych closed this Apr 8, 2025

bigludo7 mentioned this pull request Apr 8, 2025

Provide a specific document for CAMARA API Event Subscription and Notification #442

Merged

2 tasks

		The name `openId` must be same as defined in the components.securitySchemes section.


		### Mandatory template for `info.description` in CAMARA API specs


		Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object).

		The following is an example of how to use the `openId` security scheme defined above as described in [Use of security property](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-security-property):

	For example, this information can remain in browser history, could be visible to anyone who can read the URL,
	For example, this information can remain in browser history and could be visible to anyone who can read the browser history,


		#### 5.5.1. api-name

		`api-name` is what is specified as the base path, prior to the API version, in the `servers[*].url` property.

Conversation

rartych commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR introduce a breaking change?

Special notes for reviewers:

Uh oh!

rartych commented Mar 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tlohmar Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tlohmar Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rartych commented Apr 3, 2025

Uh oh!

PedroDiez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tlohmar Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rartych commented Apr 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rartych commented Mar 17, 2025 •

edited

Loading

tlohmar Mar 31, 2025 •

edited

Loading

tlohmar Mar 31, 2025 •

edited

Loading

tlohmar Apr 7, 2025 •

edited

Loading