alfresco tech talk live - rest api of the future
TRANSCRIPT
REST API of the FutureTech Talk Live
6th January 2016Gavin 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 -> OpenAPI Specification as from 1st Jan
• 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
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
Tenant
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
ScopeTenant
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
Scope API NameTenant
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
Scope API Name VersionTenant
URL Structure
…/-default-/public/alfresco/versions/1/sites/{id}/members
Present
Scope API Name Version EntityTenant
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
v0 v1 URL Comparison• GET /service/api/sites?size=5
• No paging info in response!• GET /service/api/node/{noderef}/children?skipCount=0&maxItems=5
– Actually maps to CMIS Atom XML!• POST /service/api/upload
• GET /api/-default-/public/alfresco/versions/1/sites?maxItems=5• GET
/api/-default-/public/alfresco/versions/1/nodes/{nodeId}/children?maxItems=5
• POST /api/-default-/public/alfresco/versions/1/nodes/{nodeId}
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)
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)• Enhancing REST API framework• API Definition (think WSDL)
• Swagger (Demo shortly)• API Explorer
• Swagger UI initially• Modularisation• Discoverability
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/OpenAPI Specification)– RAML (now 1.0), API Blueprint (now open source)– oData
• Webhooks• Server Sent Events• Web Sockets
Future
Future Considerations• API Management
• Design• Deploy• Keys/Authentication• Metrics• Monitoring• Integration with 3rd party tools
Future
Demo
Demo• File/Folder API• Swagger Definition & UI
Demo
Questions?