API Client Connector designs

[sjcox-rh]

Designs for UX-issue found here:
#43

Linked to epic issue:
syndesisio/syndesis-project#119

[zregvart]

I think the Security section will differ depending on the configuration needed for security.

The username/password prompt as depicted in the mockup would only make sense when defining a Connection backed by that API connector.

Let me explain, I think we will still create Connections for API Connectors, at that point we will prompt for the credentials (username/password, API tokens, Certificates) to be used with that Connection. In the Security section of the wizard to define the API Connector I see only the need to view/configure OAuth parameters (and perhaps Certificate parameters) that have been read from the uploaded Swagger specification, if we wish to allow the (admin?) users to see or change those.

[zregvart]

Do we want the users to delete API connectors? Are we then missing an option to delete the API connector, perhaps on the API connector details page?

[zregvart]

On the details page, do we want the user to modify the actions of the connector or can this be done only when the connector is defined? See syndesisio/syndesis-project#173

[zregvart]

We need to add OAuth scopes to the Security step of the new Connector wizard. When Security type is OAuth we would like to give an option to the expert user to customize OAuth scopes. OAuth scopes are a form of access grants, or delegated permissions, that are associated with the OAuth token we receive at the end of the OAuth flow. This can be a subset or all scopes, and the Swagger specification file might or might not have them defined.

According to the OAuth 2 specification, there is no limit on how much characters OAuth scope can have, and it can contain arbitrary set of letters, numbers and symbols (except for backslash).

There can be arbitrary number of OAuth scopes associated with the API.

Examples of OAuth scopes taken from the Reverb API Swagger specification: read_profile, write_profile, read_orders, write_orders, read_feedback, write_feedback, write_reviews, write_listings, read_listings, write_messages, read_messages, read_lists, write_lists, write_offers, read_offers, read_payouts, public.

Google provides a list of OAuth scopes per API, these are in a form of HTTP URLs.
I see following scenarios:

• no authentication information is provided in the Swagger specification, the expert integrator (out of bands) knows that the REST API for which the API Connector is being created uses OAuth, and picks OAuth from the Authentication Type and proceeds to specify zero or more OAuth scopes
• authentication information is provided in the Swagger specification, the expert integrator accepts that all scopes defined are chosen
• authentication information is provided in the Swagger specification, the expert integrator modifies the OAuth scopes by adding or removing individual OAuth scopes

[dongniwang]

Wanted to go ahead and post the updated designs here to get some feedback. Thanks!

I also have a few questions:

• Step 2: Review swagger actions

  • Do we want to make a whole list of actions available in the wizard UI?
  • What's the typical review action here? Do users just look at the top of the list and that's it?
  • The concern is that we have very limited screen here in the UI and the list usually contains 100+ actions.
  • @gashcrumb raised a good point about might be just showing an overview on this screen and bring users to a separate page like http://petstore.swagger.io/?url=https://syndesis-staging.b6ff.rh-idev.openshiftapps.com/api/v1/swagger.json to review actions. @gashcrumb Please add more details if I didn't explain it correctly.

• Step 3: Security

  • @zregvart mentioned the possibility of letting users add custom scopes for OAuth. @zregvart please elaborate as I'm not sure I fully understand this.

Thank you!

cc: @zregvart @kcbabo @chirino @gashcrumb @kahboom @sjcox-rh @amysueg @seanforyou23

[gashcrumb]

@gashcrumb raised a good point about might be just showing an overview on this screen and bring users to a separate page like http://petstore.swagger.io/?url=https://syndesis-staging.b6ff.rh-idev.openshiftapps.com/api/v1/swagger.json to review actions. @gashcrumb Please add more details if I didn't explain it correctly.

Yeah, so my point was we figure a swagger definition will have lots of actions, and that's a lot of content to show in the review step. Maybe it'd be better to just have a really high-level summary (like 230 actions, 400 models etc) and then have a link that opens a new window where we just re-use the swagger-ui app, i.e. maybe we just fork and host it locally for the cases where a user actually wants to look through the definition. Implementation-wise for the UI that's a lot less work, as we then don't have to go and re-implement that view, and that would make the design a bit easier as well I think.

[zregvart]

Step 2: Review swagger actions

Do we want to make a whole list of actions available in the wizard UI?
What's the typical review action here? Do users just look at the top of the list and that's it?

I really can't tell, if it was me I would like to be certain that the imported Swagger specification is the one I wanted, and have some feedback (now that I've seen the kinds of Swagger specifications there are) that it will work with Syndesis. Perhaps something along the lines:

Imported 167 operations:
 - 4 dealing with `orders`
 - 5 dealing with `categories`
 - ...

Errors:
 - Semantic error at paths./orders/{order_id}/feedback/seller.post.security.0.0: Security scope definition write_feedback could not be resolved
 - ...

Warnings:
 - Several operations don't provide output syntax (157 out of 157)
 - Required security specification is missing (Missing OAuth authorization URL, can be specified on the next screen)
 - ...

The error above was generated when I imported Reverb Swagger specification (https://s3.amazonaws.com/swagger.reverb.com/swagger.json) into http://editor.swagger.io/

The concern is that we have very limited screen here in the UI and the list usually contains 100+ actions.

In the example above it could also contain a number of errors, I've opted to have the errors detailed and warnings summarised. Does that make sense?

@gashcrumb raised a good point about might be just showing an overview on this screen and bring users to a separate page like http://petstore.swagger.io/?url=https://syndesis-staging.b6ff.rh-idev.openshiftapps.com/api/v1/swagger.json to review actions. @gashcrumb Please add more details if I didn't explain it correctly.

I think perhaps a summary is the best option, otherwise we might end up supporting a number of viewers for Swagger files (each for a new specification).

Step 3: Security

@zregvart mentioned the possibility of letting users add custom scopes for OAuth. @zregvart please elaborate as I'm not sure I fully understand this.

The creation of the new API Connector is performed by the expert integrator, and if OAuth scopes are missing from the Swagger file they might want to define them. This way when the citizen integrator creates the connection proper scopes are used. Of course this begs the question if OAuth scopes can be added to the Swagger document by the expert developer in the first place and we should not support adding new OAuth scopes?

Perhaps as a first implementation we should provide only the scopes that are specified by the Swagger file, and wait for feedback?

[dongniwang]

@zregvart thanks for all the answers.

So i think right now we'll need to add some kind of summary to step 2 instead of showing all the actions? Something similar to the followings:

Imported 167 operations:

• 4 dealing with orders
• 5 dealing with categories
• ...
  Errors:
• Semantic error at paths./orders/{order_id}/feedback/seller.post.security.0.0: Security scope definition write_feedback could not be resolved
• ...
  Warnings:
• Several operations don't provide output syntax (157 out of 157)
• Required security specification is missing (Missing OAuth authorization URL, can be specified on the next screen)
• ...

Agreed that in the first pass we probably just want to have scope selections...

[sjcox-rh]

So just to be clear, we are just going to show a summary instead of listing all actions?

Also, if we go this route, will we link to a separate page to review actions like @gashcrumb suggested?

Also, @zregvart, concerning your question about deleting a connection, the user will be able to do that on the API connector list page. But I agree that we should consider that function within the details page as well.

Thanks for updating the designs while I was away @dongniwang!

[zregvart]

Also, if we go this route, will we link to a separate page to review actions like @gashcrumb suggested?

I'm not entirely convinced that it is needed, this can always be done by the expert integrator on their own. For instance open http://editor.swagger.io/ and load the same Swagger specification there.

[zregvart]

I vote that we just go with the simplest thing that we have right now and then iterate when we accumulate some feedback. Lets update the designs with the latest work from @dongniwang have a quick stab at the review step and merge this.

[sjcox-rh]

@zregvart Alright I will change the Review Swagger Actions step to just show a review then ill update this PR with the latest designs. Thanks!

[sjcox-rh]

cc: @zregvart @kcbabo @chirino @gashcrumb @kahboom @dongniwang @amysueg @seanforyou23

Updated the PR to show a summary of swagger actions instead of a list. Also reordered the steps based on designs updates Dongni made last week.

Here is the design for the "Review Swagger Actions" step: