Add your app
Adding a new app or service by importing the API specification
You can make your app available to the huge number of Ultradox users by simply importing your API specification in Swagger 2.0 or Google Discovery format.
Importing the API
You can import your API by selecting the Import API menu item from the File menu in the Ultradox editor.
Either import the API spec from Google Drive or enter a public URL where the spec can be found.
Ultradox will then create building blocks for each method and will also generate a nice documentation for your app.
After importing the API you may have to enter additional info like the Oauth2 client secret and password if your app requires authentication .
Listed as private
You will find the new building blocks in the sidebar right after importing the API.
It will also be listed as private in the Add more dialog until you publish the API.
Optimizing the API
In order to improve the user experience you may have to optimize your API specification.
Before we can accept a new app to be listed in our public directory we have to make sure that it is easy to understand and easy to use as most Ultradox users are not developers.
Tags
Tags defined in your API spec will show up as subcategories in the building block sidebar. Make sure to give them a short and descriptive name to guide the users into the right direction.
Each operation with the same tag is sorted under the corresponding subcategory.
Icons
To get nice icons for your building blocks in the sidebar, create and publish an icon either as svg or png format with 64x64 pixels on the web and specify the URL in your spec using the x-logo extension.
You must at least specify an icon for your app in the info section of your API spec.
info:
version: '1.0'
title: Friends+Me
x-logo:
url: 'https://www.mydomain.com/friendsme.png'
...You can also specify a unique icon for each method.
When creating icons per method, each icon should reflect your app and should just add an overlay to distinguish the different methods.
If no icon is specified on method level, the generic icon of your app will be used.
paths:
/users.identity:
get:
x-logo:
url: 'https://www.mydomain.com/getidentity.png'
...Texts
Ultradox uses the info from your API spec in the Ultradox editor in various ways.
The x-summary extension in the info section of the spec will show up in the Add more dialog as description of your API.
The icon and name of your app (in this example Friends+Me) is taken the info element of your spec.
The subcategories (e.g. Users or Teams) are defined as tags.
The icon and title of each building block that show up in the sidebar are taken from the x-logo and x-title fields in each operation in your spec.
The summary of your operation will be displayed on the building block itself after dragging it into the automation.
Descriptions
The description of your api and of each operation will be used when generating the online help.
You may use markdown to format the description of your API.
Keep your audience in mind and avoid technical terms in the description of your operations.
OAuth2
Ultradox will handle the authentication for your app if the security is properly defined in your API spec.
As Ultradox runs on the server even if the users are not online, you will not be able to use the implicit oauth flow. The only flow type that is supported is accessCode.
Access tokens may expire. To be able to refresh the access tokens without user interaction you'll have to specify the x-refreshUrl in your security definition.
Example for a working security definition in yaml format:
securityDefinitions:
auth:
type: oauth2
flow: accessCode
authorizationUrl: https://api.friendsplus.me/oauth.authorize
tokenUrl: https://api.friendsplus.me/oauth.access
x-refreshUrl: https://api.friendsplus.me/oauth.token
scopes:
'admin': Administer your user account
'drafts': Access and modify your drafts
'drafts.read': Access information about your drafts
'drafts.write': Create and modify your drafts
'identity': Confirm your identity, email and avatar
...Make sure that the scopes are properly defined and the optional scopes are correctly referenced in each operation.
Publishing
Publish your API
Under construction ...
Questions and Feedback
If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.
If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.
Last Updated: 3/19/18