alfresco tech talk live - rest api of the future

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

Feedback Welcome

@olehejlskov (ole.hejlskov@alfresco.com)@gcornwell (gavin.cornwell@alfresco.com)

Questions?