Post on 23-Jan-2018
transcript
REST API of the Future
1st December 2015Gavin Cornwell (@gcornwell), Engineering Manager
Agenda
• Introduction• Past• Present• Future• Demo• Questions
Agenda
Introduction
Why?
• REST API space moving at an incredible rate, lots of stories every week
• Surge in mobile devices drove API usage• Twitter have billions of API calls per day!
• Everything has an API– Apps, IoT, SmartTVs, Cars!
• “X”aaS• Main entry point is REST API• Extension point; no in-process access
• Treated as a product not a feature
Introduction
Community
• Open API Initiative (OAI)– Google, Microsoft, IBM, 3Scale, Apigee, Restlet et al.– Linux Foundation– https://openapis.org– Swagger -> Open API Definition Format (OADF)
• Open APIs– http://apicommons.org (metadata/patterns)– http://apis.io (registry)
• Open Data– Even Government data
Introduction
Tooling
• Lots of tools emerging (new one every week)• Numerous REST clients• Amazon API Gateway• SwaggerHub• Restlet APISpark• Can do some really cool stuff!
• http://restlet.com/blog/2015/10/28/real-time-stock-quotes-from-google-finance-with-apispark/
Introduction
Past
Past
• Web Services (SOAP/WSDL)• CMIS• Webscript framework introduced• REST APIs started emerging
• Organically grew• Inconsistent URLs, parameters & responses (JSON & XML)• What’s public, what’s private?• Not very RESTful
Past
Present
Present
• Public API Framework (4.2)• Built on top of webscript engine• Set of internal RESTful guidelines• Consistent URLs, parameters & responses• Proper use of HTTP status codes
• On-Premise and Cloud support• /alfresco/api/-default-/public/alfresco/versions/1
• Ticket and Basic Auth• api.alfresco.com/{network}/public/alfresco/versions/1
• OAuth only
Present
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
Scope API Name Version Entity RelationshipTenant
URL Examples
• …/-default-/public/alfresco/versions/1/sites• …/-default-/public/workflow/versions/1/processes• …/-default-/public/cmis/versions/1.1/atom• …/-default-/private/alfresco/versions/1/cmm• …/-default-/extension/my-company/versions/1/my-entity
Present
Entities
• Nodes• Sites• People• Tags• Workflow• Networks (Cloud)
Present
Confusion
• REST API; which one?– /service/api– CMIS– Alfresco One API
• Anyone know what this is?• 5.1 addressing this
– v0 REST API– v1 REST API– CMIS API
Present
5.1 Enhancements
• Stronger, clearer API support policy• v0 REST API moved to limited support• Backwards Compatibility Kit (BCK)• Documentation overhaul
• http://docs.alfresco.com/5.1/concepts/welcome.html (EA)• More details from Ole later
Present
Future
The following slides show roadmap information, it is not a commitment to implement those features and the information presented is subject to change.
Future
Working On Now
• v1 API investment• Node Entity (File/Folder) (Demo shortly)• Discoverability
• Enhancing REST API framework• API Definition (think WSDL)
• Swagger (Demo shortly)• API Explorer
– Swagger UI initially
Future
Future Considerations
• Functional equivalence to v0 REST API• Client Libraries
• Mobile (Android & iOS) already available• Java, JavaScript• Others generated from API definition
• Contract-first design– Developers and technical authors– Generate boiler plate code for server & client– Community via pull requests
Future
Future Considerations
• Monitor standards– HATEOAS
• Hypermedia As The Engine Of Application State• Roy Fielding; Level 3• HAL, Siren, JSON-LD, Collection+JSON etc.• CMIS Atom; kind of!
– OAI (Swagger/OADF)– RAML, API Blueprint– oData
• Webhooks• Web Sockets
Future
Future Considerations
• Tooling (Lifecycle Management)• Design• Deploy• Keys/Authentication• Metrics• Monitoring• Integration with 3rd party tools
Future
Demo
Demo
• CMIS vs File/Folder API– Payload difference, size & speed
• Swagger Definition & UI
Dem
o
Feedback Welcome
@olehejlskov (ole.hejlskov@alfresco.com)@gcornwell (gavin.cornwell@alfresco.com)
Questions?