[WIP] Add swagger docs for new OEM partners API #454

lcaparroz · 2021-04-06T12:36:28Z

In this pull request I implement Swagger for documenting the OEM partners API.

We need to document the new API for pre-activation of OEM partner orders (to be implemented yet). As a first start, I documented the current API with Swagger/OpenAPI.

In this commit, I add documentation for the coming endpoints `partner_orders/pre_activation` and `partner_order/renewal`, which are yet to be implemented.

api_docs/swagger/swagger.yaml

lagartoflojo · 2021-04-07T12:45:35Z

doc/OEM-Partner-API.md

@@ -1,5 +1,17 @@
 The purpose of this document is to describe the way of communication between OEM partners and SUSE Customer Center API.

+A Swagger documentation is available in this repository. You just need to server it locally with the following commands:


Suggested change

A Swagger documentation is available in this repository. You just need to server it locally with the following commands:

A Swagger documentation is available in this repository. You just need to serve it locally with the following commands:

lagartoflojo · 2021-04-07T12:46:59Z

api_docs/swagger/swagger.yaml

+    `APIAuth-HMAC-SHA256 112233:wvSi7Ach641iUvDTVE5AEVQCwXdH0uSfUQecJTlLSIolxVmqmk7gESkUIi+65R4x6OcDNy6ytVNBbQ5hlLzBpH0V3QolvYFHRgwQqcGhcbSDrUX7nQyVREilfVJ4FYaIirBnfXWYwi9K43bXHcEWj/mBQ1A8c7vpViWpalCdf8M=`
+
+servers:
+  - url: "{protocol}://scc.suse.com/api/oem"


Is that {protocol} bit required? I just ask because we really only accept HTTPS, and it looks weird in the UI:

lagartoflojo · 2021-04-07T13:25:39Z

api_docs/swagger/components/requestBodies/partner_order_payload.yaml

+        required: true
+        type: array
+        items:
+          $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderItemPayload'


In general, I miss the description of these fields.
What are they for? Do they need to follow a format? Do they have any validations?
And also importantly: what does SCC do with the data?

For example:

Does OEM token need to be unique?
In the case of in-activated subs, we could document that end-users need to use the token to claim their subscriptions; in the case of pre-activated subs, end-users don't need it, but we should state that the renewal order needs to have the same token as the original order, etc.

Email: do we send the user something? Is only 1 email allowed?

starts at: how does the end date get calculated? does it really need to be a date-time, or can we allow a simple date?

end_user_account_number: what is this for? Does it need to follow a format?

lagartoflojo · 2021-04-07T13:27:38Z

api_docs/swagger/paths/partner_orders.yaml

+        schema:
+          $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderPayload'
+  responses:
+    '200':


Is 200 the only possible response? What about errors? How are they presented, in terms of error code and message format?

lagartoflojo · 2021-04-07T13:28:39Z

api_docs/swagger/paths/partner_orders/pre_activation.yaml

+    - $ref: '/swagger/swagger.yaml#/components/parameters/Date'
+    - $ref: '/swagger/swagger.yaml#/components/parameters/ContentMd5'
+    - $ref: '/swagger/swagger.yaml#/components/parameters/Authorization'
+  summary: Place a pre-activated OEM partner order


Do we explain somewhere the difference between a "pre-activated" partner order and "regular" (?) partner order?

lagartoflojo · 2021-04-07T13:33:41Z

I know I left a lot of comments, but don't take it the wrong way =) I think this is a GREAT improvement over our existing documentation!

lagartoflojo · 2021-04-08T13:32:18Z

api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml

+        required: true
+        type: string
+        example: 987654
+      end_user_account_number:


Can we accept UC site id's here, in addition to SF account numbers?
I ask because brand new SUSE customers will not have a SF account number.
Right now, we allow customers to enable OEM subs on a UC org, and at that point we create the account in SF and assign its SF account number.

Do you think we should work only with the UC site IDs then? If this is data which the end user can always inform OEM partners, maybe it's a better option to consider.

Otherwise, do you think we should accept both UC site IDs and SF account numbers?

From what I understand, most FJ customers are also SUSE customers, so they will have an SF account number.
But there will be some that are not SUSE customers yet, and will therefore not have an SF acct num.
Therefore, I think we could accept both.

lagartoflojo · 2021-04-09T12:55:34Z

api_docs/swagger/paths/partner_orders/renewal.yaml

+      content:
+        application/json:
+          schema:
+            $ref: '/swagger/swagger.yaml#/components/schemas/PartnerOrder'


From the call today, did I understand correctly that renewal partner orders do not need to receive a starts_at nor a the end user account number?

Yes, this is right. And also I understand that there'll be no use for the expires_at date once subscriptions' lifespans will be computed using the SKU duration.

Ok; I think we are still displaying those fields in the docs for the renewal endpoint though, aren't we?

Yes, the PartnerOrder schema is the same in all endpoints, just the payloads differ.

Oh, yes, I commented on the wrong line, sorry! I meant about the payload. Are the different payloads for new/renew orders documented?

Yes, if you check the request body section of each operation, there is Example value, and then you can switch to Schema

I'm improving the field and operations descriptions to match the the same style used in the SCC API Swagger.

suse-tests-pass · 2021-07-29T09:57:01Z

Well Done! Your tests are still passing.
https://ci.suse.de/job/SCC-Connect-Prophet/425019/console
If the given link has expired,you can force a Prophet rerun by just deleting this comment. (Merged b46f3e2 into 1b377c9)

lcaparroz · 2021-08-10T12:54:53Z

Closing this PR since we moved the Swagger documentation to https://scc.suse.com/connect/v4/documentation/.

Add swagger docs for existing API

ff6c1fe

We need to document the new API for pre-activation of OEM partner orders (to be implemented yet). As a first start, I documented the current API with Swagger/OpenAPI.

lcaparroz self-assigned this Apr 6, 2021

lcaparroz added 3 commits April 6, 2021 10:13

Change directory structure for swagger files

15157a5

Break swagger.yaml into smaller files

ade9e4c

Add swagger docs for OEM pre-activation/renewal

a328427

In this commit, I add documentation for the coming endpoints `partner_orders/pre_activation` and `partner_order/renewal`, which are yet to be implemented.

SUSE deleted a comment from suse-tests-pass Apr 6, 2021

Add instructions to run Swagger (OEM partner API)

f646c2c

SUSE deleted a comment from suse-tests-pass Apr 6, 2021

lagartoflojo reviewed Apr 7, 2021

View reviewed changes

api_docs/swagger/swagger.yaml Show resolved Hide resolved

lagartoflojo reviewed Apr 7, 2021

View reviewed changes

Fix typo in OEM Swagger docs and apply suggestions

0aee100

lagartoflojo reviewed Apr 8, 2021

View reviewed changes

lagartoflojo reviewed Apr 9, 2021

View reviewed changes

lcaparroz added 2 commits April 12, 2021 10:14

Add description to payload fields

3358595

Improve the descriptions of request bodies

f329e89

SUSE deleted a comment from suse-tests-pass Apr 13, 2021

Add details description to Swagger paths

b46f3e2

SUSE deleted a comment from suse-tests-pass Apr 16, 2021

SUSE deleted a comment from suse-tests-pass Apr 21, 2021

SUSE deleted a comment from suse-tests-pass Jun 28, 2021

SUSE deleted a comment from suse-tests-pass Jul 16, 2021

SUSE deleted a comment from suse-tests-pass Jul 20, 2021

SUSE deleted a comment from suse-tests-pass Jul 29, 2021

lcaparroz closed this Aug 10, 2021

lcaparroz deleted the new-partners-api branch August 10, 2021 12:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Add swagger docs for new OEM partners API #454

[WIP] Add swagger docs for new OEM partners API #454

lcaparroz commented Apr 6, 2021

lagartoflojo Apr 7, 2021

lagartoflojo Apr 7, 2021

lagartoflojo Apr 7, 2021 •

edited

lagartoflojo Apr 7, 2021

lagartoflojo Apr 7, 2021

lagartoflojo commented Apr 7, 2021

lagartoflojo Apr 8, 2021

lcaparroz Apr 8, 2021

lagartoflojo Apr 8, 2021

lagartoflojo Apr 9, 2021

lcaparroz Apr 9, 2021

lagartoflojo Apr 9, 2021

lcaparroz Apr 9, 2021

lagartoflojo Apr 9, 2021

lcaparroz Apr 9, 2021

lcaparroz Apr 9, 2021

suse-tests-pass commented Jul 29, 2021

lcaparroz commented Aug 10, 2021

		@@ -1,5 +1,17 @@
		The purpose of this document is to describe the way of communication between OEM partners and SUSE Customer Center API.

		A Swagger documentation is available in this repository. You just need to server it locally with the following commands:

[WIP] Add swagger docs for new OEM partners API #454

[WIP] Add swagger docs for new OEM partners API #454

Conversation

lcaparroz commented Apr 6, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lagartoflojo Apr 7, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lagartoflojo commented Apr 7, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

suse-tests-pass commented Jul 29, 2021

lcaparroz commented Aug 10, 2021

lagartoflojo Apr 7, 2021 •

edited