General principles doc

[shilpa-padgaonkar]

1. Clarify supported spec format (oas3 vs swagger2), Should async api spec be included for special cases?
2. Decide on the criteria to go from step 3 (implementation) to step 4 (validation)

[jordonezlucena]

1. We don't have a strong preference here, though we understand that standards have started to migrate solutions to OAS3. So let's go for OAS3. We agree that we should support both sync (200/201 response code) and async (202 response code) API spec. Note that support of async API is subject to capabilities of underlying assets and bound to specific operations (e.g. feasibility check, etc.).
2. The criteria to from step 3 to step 4 should build on the following guidelines: At least one independent method 100% implemented. In case a method "X" has dependencies with other methods "{Y,Z}", for method "X" to be validated, methods "{Y,Z}" need to be implemented as well.

[Kevsy]

Worth considering the OMA RESTful API guidelines, developed by operators including DT and Vodafone (me :)) . Although it is 10 years old there are principles we can adopt, or at least consider the section headings. It covers:

• USE OF REST GUIDELINES
• UNSUPPORTED FORMATS
• AUTHORING STYLE
  -- Names
  -- Case usage for names
• CONTENT TYPE NEGOTIATION
• RESOURCE CREATION
  -- General procedure of resource creation
  -- Error recovery during resource creation
• JSON ENCODING IN HTTP REQUESTS/RESPONSES
  -- Serialization rules: Instance-based JSON generation
  -- Serialization rules: structure-aware JSON generation
  -- Rules for JSON-creating and JSON-consuming applications
• ENCODING AND SERIALIZATION DETAILS FOR MIME FORMAT
• RESOURCE URL CONSIDERATIONS
  -- Resource URL structure
  -- API version signaling
  -- Handling of unsupported versions
• BACKWARD COMPATIBILITY
• DATA ITEMS
• ADDRESS DATA ITEMS
• COMMON DATA TYPES
  -- Structures
  --Enumerations
• CHARGING
  -- Charging data type
• ERROR HANDLING
• HTTP RESPONSE CODES
• HANDLING OF NOT ALLOWED HTTP METHODS
• HTTP RESPONSE CODES IN RESPONSE TO NOTIFICATIONS

There is also an annex with examples, etc.

[jordonezlucena]

Thanks @Kevsy for your gr8 comments.
We're now working on a document to capture this and other information. I've generated a new deliverable whose ToC is available here: https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Deliverables/General-principles-doc.md

[jordonezlucena]

The stable version is available now -> https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Working/Guidelines%20API%20v1.0.0%20-%20CAMARA.pdf

[T-sm]

Thank you for your contribution!
This document is now available for review in Issue #32 Review General Principles doc.
The current issue is going to be closed, please use Issue #32 for review purposes.