API Design

[namrathadeepthi]

Minutes of the meeting (5th July 2016) Agenda: Clearly identify the interfaces of components.

• Ensuring abstraction boundaries between layers are intact:
  • In this meeting, the idea of a component was clearly established and each layer was strictly defined.As shown in the picture below, there exists two interfaces for each component, upper and the lower interface. (Every vertical line is an interface). Link: https://docs.google.com/drawings/d/1JfzCe7uEEk25KLSv77QFbxkjqcAWQvBCEtNJ-BfKi20/edit
  • The upper interface of Rest takes in URLs and returns JSON. Rest cannot refer to objects.
  • The lower interface of Rest makes a call to System interface using Strings and gets back a dictionary.
  • The lower interface of the System interface makes a call to the System API (consisting of Strings or Objects) and gets back objects. The lower interface of the System makes a SQL Alchemy call to the entities which in turn uses SQL queries to interact with the database.
  • So, the main motivation behind this design was safety and flexibility in evolution. At all times, the invariance of the 'runtime' has to be maintained.
• Reuse of code:
  • We try to follow the DRY (Do Not Repeat Yourself) convention as far as possible. So, to achieve this objective we use handlers for the system using persistence. The handlers save the objects to the database. This way we do not have to re-write the code for system implementation.
  • Methods like update_user(id) should be implemented in the System interface and this method in turn invokes update_user(user,...) and finally returns a dictionary.
• What does System do? Does it allow you to create entities? No, was the answer discussed in the meeting. We can just change/manipulate the state of the System. System's job is to maintain the invariant.
• Important points:
  • System API should not return objects to REST.
  • Implementing handlers (persistent- system handler) by over-riding the methods.
  • Security and flexibility of code should be maintained throughout by ensuring clear abstraction boundaries between layers.
  • Try out this design on a small scale using the User-Directory web-app.

[travula]

The outcome of this meeting is captured by the milestone https://github.com/vlead/outreach-portal-3.0/milestone/5

[travula]

System Interface Design

https://docs.google.com/drawings/d/1MlZJu82jXhQ7LZNWCcCU8z2YBcRsXBBH_EVqRwaxxtg/edit?usp=sharing