An properly designed API for either mobile apps or 3rd party access needs to be built with maintainability, security, version control, data volume optimisation and speed performance in mind. Rod Hemphill from Melbourne App Development explains the options and his experience.
2. PROBLEM STATEMENT
• Management Advantage Pty Ltd provides administration and other solutions
for aged care facilities in Australia.
• There core system is an Entity Framework desktop Aged Care administration
system.
• They had an existing API built for their staff mobile app and needed to:
• provide an API to a new mobile app to support family members of clients, and
• an API to support third parties to provide other solutions such as catering and
maintenance.
• How do you do this?
3. THE CORE SYSTEM
• An extensive solution providing:
• client administration,
• ACFI appraisals,
• Medicare claims,
• client care,
• client assessments,
• care planning,
• progress management,
• graphical charting,
• client, management and healthcare professional communications,
• facilities maintenance,
• compliance audits,
• employee management,
• police checks,
• courses and certificate management,
• invoicing,
• banking
….. It’s big and comprehensive.
• Entity Framework .Net system using Forms, SQL Server with about 1500 tables.
4. STAFF APP
• Intended for client support staff to provide the following services:
• Record chart information (e.g. blood glucose level, heart rate etc)
• Provide staff with client personal information (e.g. life story, family details)
• Evacuation Aid
• ACFI reporting
• Activity events management (e.g. Bingo attendance)
• Xamarin Forms, Android and iPhone, oAuth session based authentication.
• Uses the camera.
• 60 pages, 3 graphic charts using telerix.
• Sqlite database with 117 tables.
• Designed to work offline hence keeps a copy of large amounts of operational data.
One medium sized client has 27,800 records stored locally and kept in sync.
5. FAMILY APP
• For family members of clients to communciate with health care professions, see
what their parents activities, provide feedback and maintenance request.
• Xamarin Forms, 17 pages.
• Social media and standard session based oAuth authetication.
• Push notifications, camera support.
• Sqlite with 20 tables, and a small volume of data.
• Firebase Deep Linking onboarding.
6. API FOR THIRD PARTY ACCESS
• Generic API for third party access to data.
• Uses: Catering services, facilities maintenance.
• Issued encrypted security key access.
• Continually growing.
7. DIFFERING REQUIREMENTS
Staff App Family App 3rd Party Access
Speed of transfer ✔ ✔
Volume of data optimisation ✔
Data synchronisation (always in sync) ✔ ✔
Simplistic flat data formats ✔
Ever evolving functionality ✔
New interfaces ✔
Require stable interfaces ✔
Maintainability ✔ ✔ ✔
8. API DESIGN CONSIDERATIONS
1. Maintainability, extensibility, expandability.
2. Security
3. Version control.
4. Data volume optimisation.
5. Speed performance.
9. 1. MAINTAINABILITY
Single or many API’s?
• Originally one for apps and one for 3rd party API.
• Now a single API.
• The architecture is complex, but the real maintenance is the functional changes.
REST
• Inherently flexible.
• Supports flat and hierarchic data.
• Internal systems can compromise flexibility for redundant data.
• You will need to pass parameters to handle complexity. We use “App-Name”.
10. 2. SECURITY
Differing options:
• Flat private key.
• Hashed private / public key. (Used for high security currency transations).
• Username/Password session based.
• Username/Password initiated oAuth, with sessions.
Management Advantage Chose:
• Flat private key for 3rd party
• Username/Password initiated oAuth with sessions.
• Use Https.
11. 3. VERSION CONTROL
Servers architecture:
1. Central server per client.
2. Centralised, single version, multi-
tenanted cloud based system.
Problem:
• You don’t have any control when the user
downloads an app.
• The app version could be behind or
ahead of your API.
• Your API could be ahead or behind your
app.
• i.e. your API needs to allow for App
versions that haven’t been written yet.
12. 3. VERSION CONTROL - IMPLEMENTATION
• Learnings:
• Don’t store app versions as strings. Use the inbuilt C# Version class.
• Pass the version of each system in the Request and Response headers.
(e.g. “X-API-VER” and “X-APP-VER”)
• Remember that the App will not know the API version when it first starts a session.
• Default to REST and Json wherever possible. Very forgiving.
• You will need to hard code ‘if tests’ for version numbers in both the API and App.
Ensure you use the [Obsolete] attribute with the version number where possible.
• Where not possible make sure you throw out debug messages when the ‘if tests’ should be
cleaned up.
• Have auto-updating database version control in your apps.
Naming our connection string as “/V1/xxxx” had little value. We use “/API/xxxx”.
13. 4. DATA VOLUME OPTIMISATION
• App needs to separate business logic from data transfer:
• Models support full business logic. (e.g. Client, Address, HCP)
• DTO’s optimised for data transfer. (e.g. ClientDto, AddressDto, HCPDto)
• Optimise Json with “DefaultValueHandling” – don’t transmit nulls.
• LastChangeDate.
https://manad.com.au/api/client?lastChangeDate=20180715T13:10:31.102
• We use a generic process.
Only use server side UTC dates. Never app device dates.
• Server should always send the “RunDate” – don’t rely on record LastUpdatedTimestamp.
14. 4. DATA VOLUME OPTIMISATION (CONT)
• For complex data structures, don’t resend data if already sent.
We created a “DtoSession” class.
ClientDto (recursive structure)
• AddressDto Address
• AddressDto MailingAddress
• List<HCPDto> HCPs
• AddressDto Address
• List<ClientDto> ClientContacts
• AddressDto Address
• (etc)
15. 5. SPEED PERFORMANCE
Considerations:
• Http overhead: A call per record type? One call and fully cascade data?
• Decision came down to what we could run on background threads:
• Initial startup you need data before show a page.
• Ongoing you can show last data and update with ObservableCollections.
• Do you have the Apache “KeepAlive” option?
• Reduced data has marginal effect on transmission performance:
• (802.11b should get at least 100 Mbytes per second)
• Real impact on speed is:
• Optimising your server enquiries.
• Optimising your app processing.
• Minimising the data usually reduces the app processing time.
• ... But may not reduce the server processing time.
16. 5. SPEED PERFORMANCE (CONT)
• We use NewtonSoft JSON which is fully functional:
• Supports streaming for http content.
• Allows us performance tuning options through scheme definitions and direct coding (if required in
the future).
• Compression or not?
• Overhead to compress and decompress outweigh benefits?
• Our research (not tested) said https you get better performance overall.
• We had to do https anyway, but we did not turn on http compression.