![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”.](https://image.slidesharecdn.com/apiarchitecturepresentation-180718124049/85/Architectural-considerations-when-building-an-API-12-320.jpg)
Architectural considerations when building an API
- 1. API ARCHITECTURE FOR MOBILE APPS ROD HEMPHILL MELBOURNE APP DEVELOPMENT
- 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.
- 17. QUESTIONS / DISCUSSION ROD HEMPHILL - MELBOURNE APP DEVELOPMENT