Syndesis: As an expert integrator, edit an API definition when creating an API connector

[kcbabo]

As an expert integrator, I often have API definitions that need to be cleaned up a bit prior to generating an API connector. This includes adding documentation to resource definitions, adding/deleting/changing resource operations and dealing with any errors in an API definition. My expectation is that editing will be available as part of the API import workflow as follows:

1. Create API connector
2. Point to API definition in file or URL
3. Existing summary page of resource operations in API definition
4. If I'm happy, click done to create connector. If I want to change the API definition, select "Edit API Definition".
5. Edit API definition in embedded Apicurio interface within Syndesis.
6. Return to summary page view which should refresh based on edited API definition
7. Click done or edit the API definition some more

The transition between the exiting API Connector wizard and the Apicurio wizard must be seamless. I do not want to have to login to Apicurio separately, provide URLs/locations to the API definition or perform any activity other than directly editing the API definition that I provided to Syndesis. I also need a clear way to signal that I'm done editing the API definition so that I return to Syndesis with an updated API summary. I should be able to cancel/abandon the editing process at any time and have Syndesis continue on with the original API definition.

[kcbabo]

@gaughan - FYI

[kahboom]

@kcbabo - @seanforyou23 raised a good point, as I myself was a bit confused -- can we update step 5 to instead say something along the lines of "Edit API definition in Syndesis-embedded Apicurio editor"?

[kcbabo]

Are we sure it will be embedded? If so, then happy to make the update. I was leaving it open pending the decision on whether Apircurio was embedded or in a separate tab. As much as I'd like to, I'm trying not to force implementation choices in my user stories. :-)

[kahboom]

Hey! We can leave it open, no problem. I just wanted it to be clear to everyone that we are going with the embedded approach (at least for the foreseeable future). We just had a meeting for the integration and are all now on the same page that it will be embedded for the first POC, so that's what matters, I hope. 😂 That is all subject to change if things go wrong though, so maybe it's wiser to leave it open?

[kcbabo]

Awesome, embedded it is! I need to learn to dream big with this team. :-)

[zregvart]

We rarely disappoint when it comes to promising stuff.

[mastepan]

@kcbabo can you please define more specific user story that we should follow when writing tests?
The crucial point is number 5: Edit API definition in embedded Apicurio interface within Syndesis.
Thanks

[zregvart]

@kcbabo can you please define more specific user story that we should follow when writing tests?
The crucial point is number 5: Edit API definition in embedded Apicurio interface within Syndesis.

Apicurio allows you to edint anything in the OpenAPI specification, perhaps the simplest use case would be enough. Something like changing the summary or description of an operation and seeing that reflected in the action name/description of the created connector.

[kcbabo]

Adding @gaughan ...

From a Syndesis perspective, we need to test the following cases:

• User adds one or more resources with operations (e.g. /foo, PUT and GET) in the OpenAPI definition while editing in Apicurio. When returning to Syndesis, the review page should be updated with the new resource(s).
• User deletes one or more resources in the OpenAPI definition while editing in Apicurio. When returning to Syndesis, the review page should be updated and not show the deleted resource(s)
• User updates security settings in Apicurio. When returning to Syndesis, the connector configuration page should show the updated security details.
• User adds or updates endpoint details (e.g. path, base URL) in the OpenAPI definition while editing in Apicurio. When returning to Syndesis, the connector configuration page should show the updated defaults for these settings.
• User does nothing in Apicurio, e.g. they start to edit and decide to do nothing or cancel. When returning to Syndesis, the review page should be identical to the state prior to entering Apicurio.

[kahboom]

Done. We should create a separate user story for enhancements/additional features related to Apicurio (e.g. showing additional details in the Review step, API discovery).