tech talk live - 5.2 rest apis

5.2 REST APIsTech Talk Live

8th February 2017Gavin Cornwell (@gcornwell), Software Architect

Agenda• REST API Recap• Documentation• What’s New• Enhanced APIs• Demo• What’s Coming• Questions

Agenda

REST API Recap

REST API Recap• Not that new ;-)

• v1 “Public” API first added back in 4.2!• “v1” naming introduced in 5.1• Next slide shows how to identify a v1 API

• Framework built on top of webscript engine• Set of internal RESTful guidelines• Versioned API• Consistent URLs, parameters & responses• Proper use of HTTP status codes• The API for all new clients

Recap

URL Structure

…/-default-/public/alfresco/versions/1/sites/{id}/members

Recap

Scope API Name Version Entity RelationshipTenant

Documentation

7

API Explorer• http://api-explorer.alfresco.co

m• https://github.com/Alfresco/re

st-api-explorer• http://artificats.alfresco.com

– GAV: org.alfresco.api-explorer (5.2.e/5.2.0)

• Source of truth• Generate client side binding

8

Blog Post Series• http://

community.alfresco.com• Postman collections• 7 so far, more planned:

– Sites– Search– People– Discovery– Trashcan– Permissions & Groups

New APIs

What’s New• 56 new endpoints!• Framework enhancements

– fields query parameter– include query parameter (API specific)– Operations

• Authentication API• Discovery API• Search API

New

URL Structure - Operation

…/-default-/public/alfresco/versions/1/nodes/{id}/copy

New

Scope API Name Version Entity OperationTenant

Core API• /nodes/{nodeId}

– Navigation– Content– Information– Associations– Copy, Move, Lock

• /nodes/{nodeId}/renditions• /nodes/{nodeId}/versions

New

Core API• /deleted-nodes• /queries

– Simple pre-canned queries designed for “live” search– /nodes– /people– /sites

• /shared-links– /shared-links/{sharedId}/email– Expiration

New

Authentication• /alfresco/api/-default-/public/authentication/versions/1/

tickets– Login– Logout– Validate

New

Discovery• /alfresco/api/discovery

– Version information– License information (Enterprise only)– Status

• isReadOnly• isQuickSharedEnabled• …

– Installed modules

New

Search• /alfresco/api/-default-/public/search/versions/1/search

– Low level search API (effectively exposes Java API)– AFTS, CMIS, Lucene support– Faceting– Spellcheck– Term highlighting– Search nodes, versions or deleted-nodes

New

Enhanced APIs

Enhanced APIs• /sites

– Create site (no custom preset support yet)– Update site details– Delete site

• /people– List people (no filtering)– Create person– Update person

• Enable/Disable (admin only)

Enhanced

Demo

Postman Collection• https://

www.getpostman.com/collections/e28cf833734602fb4609• File -> Import -> Import From Link

Demo

What’s Coming

Coming in 5.2.1• Groups• Downloads• Audit• Repository Actions• Enhancements

– Avatar support for person– Retrieve content & renditions of deleted nodes– relativePath property for nodes– score property for /queries/nodes (EA feedback)

Coming

Questions

Why is the API Explorer released separately?• We wanted something for 4.2 -> 5.1• Allowed us to get api-explorer.alfresco.com launched

quickly• Fix spec issues without requiring a product release• API first approach, not generated• Weren’t sure if embedding was the best way forward

– Now realised it is!– Re-use of common models– Dynamic based on installed modules

Questions

What about CMIS?• Not going anywhere• Still fully supported• Great option for homogeneous environments• We didn’t want to force people to learn/handle two APIs• Performance first approach

Questions

Where’s the AMP?• Not just a thin layer• Core services were changed to support requirements

– NodeService• Canned queries

– LockService– QuickShareService

• Overriding core services in an AMP is a bad idea!!

Questions

Can we extend the API?• Yes and No

– New APIs can be added using @annotations– No official extension points

• Consistent, stable, documented, upgrade proof API• Hopefully flexible enough for most requirements

– If not, please let us know!!• You can still use webscripts and mimic v1 structure

– /search API is implemented this way– Extract helpers to aid in building responses

Questions

Are you going to expose other services?• Definitely!• 5.2.1 should add groups, audit, actions• 6.0 will add many more• Again, feedback more than welcome!

Questions

Any live questions?Questions