API Proposal Divy

API Proposal Divy.md

Client library.

We’re planning to ship our app as a self contained library in form of UMD module.

• How to consume?
  We will serve the library from some CDN, currently we will serve only “latest” version of the application(since we’re in active dev and bugfix state) so consumer won’t need to care about versioning. At some later point we might intruduce some versioning once reach the stable version.

• How will it look like?(this is pseudo code and should not be considered as any existing or planned API contract).

  // your html page
  <script src="<our-cdn-endpoint>/latest/hq.min.js">
  <div id="hq-root"/>  // the root DOM element where the HQ app will be rendered
  //
  

  // some root of the application where app bootstrapping happens
  var hqConfig = {
  clientId: '<the id of the app we will provider to you>',
  clientKey: '<the secret key of the app we will provide to you>',
  theme:{ //optional. API fo you to override some styles in the HQ app like color for buttons etc.
  // form will be defined
  },
  customizations:{
  theme: {
  buttonSuccess:,
  buttonDisabled:,
  ...
  },
  components: {
  createNew:{ //name of our component
  createNewFromTemplate: { // name of the component extension to be registered
  type: 'button'
  action: '<some function>'
  }
  }
  }
  }
  }
  //later in code 
  HQ.setup(hqConfig, 'hq-root') // provide the config and DOM node id where the HQ will be rendered
  

  NOTE: Provided info is the conceptual view not the actual implementation. That means the concept will not change, but the details like naming, properties will/could change.

  Such setup should setup everything you need to run HQ inside your app.
  Apps with similar UI Embedding API

  • https://www.pubilling.io/

API

We will extend our API to support the Organization concept.
The Organizations API will give such endpoints:

api/v1/Organizations will return all Organization resources for authorized user

Organizations endpoint

POST api/v1/Organizations create new organization resource
GET api/v1/Organizations get all organizaitons for given app credentials (clientKey, clientSecret)
GET api/v1/Organizations/<id> get Organization resource by id

Users endpoint - only for admin purposes

GET api/v1/Organizations/<id>/users - returns array of users associated with given organization
POST api/v1/Organizations/<id>/users - creates new user in the given organization
PUT api/v1/Organization/<id>/users/<userId> - updates existsing user. Optional for MVP
DELETE api/v1/Organization/<id>/users/<id> - deletes given user from organization

Library endpoint -

GET api/v1/Organizations/<id>/library
POST api/v1/Organizations/<id>/library
DELETE api/v1/Organizations/<id>library

Authorization

There are several possible options as of now:

1. Users need to authorized in HQ as well as in main application (MVP)
   • UX is worse
   • The simplest as of now
2. OpenID connect. Needs invetigation by me also, since HQ currently does not support it.
3. Custom solution. We compute some access token based on the clientId, clientSecret(credentials of the APP itself) and user email.

Best case: HQ.Setup() should use an expirable token (probably best JWT token) that is requested from their back-end to ours and they use to init our app. Maybe we can use something for this like: http://docs.identityserver.io/en/latest/ , Auth0 or Firebase

Estimated Time

3-4 weeks workload
This does uses minimal security option 1.
We can continue the security development after.

Questions for divy

• Show the application divy!
• Explain how they currently do autorization
• Team Drives / Dropbox for Teams (priority?)
• Timeline project?
• Customizations
  • Styling (colors, fonts, etc.)
  • Callbacks ( ContextMenu, CreateMenu, …)
  • Disable features