1

Social Networks For Enterprises Your Enterprise Social Network

Developing using the REST API

2

Agenda

REST API overview REST API services OAuth authorization Let’s play with the API REST API entities PHP API client

3

REST API overview

The REST API gives you access to the most of the features you see in our web app and lets you extend them for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Zyncro web interface. Use our REST API to create applications and web sites that natively integrate with Zyncro The REST API is a collection of web services, which means that you can create Zyncro applications using any modern programming language and operating system on any computer connected to the Internet. OAuth 1.0a protocol is used to provide authorized access to our REST API services. HTTP REST services use JSON format in their responses.

4

REST API overview

You access a resource by sending an HTTPS request to the Zyncro API server. The server replies with a response that either contains the data you requested, or a status indicator, or both. The format of the URL to access the API is, for example, https://my.sandbox.zyncro.com/api/v1/rest HTTP methods separate API actions

GET is used to retrieve a representation (or, "stuff") from a resource or a collection of resources.

POST is used to create or modify a representation of a resource (we do not use PUT).

DELETE is used to remove the information about a resource.

5

REST API overview

HTTP status code in responses:

200 The request was successfully received, understood, and accepted.

4xx An error in the request. Usually a bad parameter.

5xx The request is fine, but something is wrong on Zyncro’s end.

Our REST API is split up into different areas, which contain a subset of services grouped by functionality.

6

REST API - Use

We are using the REST API, for example, in these integrations and native apps

7

Play with REST API

Show me the money!

http://apidocs.sandbox.zyncro.com/

8

REST API services

• Manage the organization configuration

• Manage organization's users (add/edit/remove)

• Edit organization properties

• Only admin users can have access to these services

Organization services /api/v1/rest/organization

• Manage user profiles

• Access follower/following user lists

• Edit user profile, change user’s profile image

• Follow/Unfollow users

Users services /api/v1/rest/users

• Access and publish in all microblogging, including Personal feed, Corporate feed, Department feeds, Private messages and Messages from Groups

• Access user's inbox events and notifications

Microblogging and Activity Stream & Inbox services

/api/v1/rest/wall

• Create new groups

• Download, edit, and upload documents to groups

• Manage group members, folders and files

• Join/leave open groups

Groups services /api/v1/rest/groups

9

REST API services

• Create new departments

• Download, edit, upload documents in departments

• Manage department members, folders and files

• Follow/unfollow departments

Departments services /api/v1/rest/departments

• Manage invitations.

• Send, accept, decline invitations

• Access the list of pending invitations

Invitations services /api/v1/rest/invitations

• Create new tasks.

• Edit task and access to the tasks of groups

• Access to the list of tasks

Tasks services /api/v1/rest/tasks

• Manage apps (add/edit/remove)

• Enable/disable apps ZyncroApps Services

/api/v1/rest/apps

10

OAuth authorization - REST API

1) Get a Request Token

2) A User have to authorize the Request Token

3) Exchange the authorized Request Token for an Access Token

4) Use the Access Token to invoke REST API services

11

OAuth types in REST API

We have three ways of getting an Access Token to invoke REST API services

Web browser authorization Get a Request token Authenticate the user using a Zyncro login web page Get an Access token

External service authorization

Get a Request token Authenticate the user using an external service Get an Access token

ZyncroApp authorization

Use combined with ZyncroApps when the user is already logged in Zyncro. We’ll see it while seeing ZyncroApps development.

Examples soon to come!

12

Java sample - REST API

Sample showing how to get the profile of a User using the REST API

public final static String API_KEY = ... public static final String API_SECRET = ... public final static String ACCESS_KEY = ... public final static String ACCESS_SECRET = ... OAuthService service = new ServiceBuilder() .provider(ZyncroApi.class) .apiKey(Paths.API_KEY) .apiSecret(Paths.API_SECRET) .build(); OAuthRequest request = new OAuthRequest( Verb.GET, "https://my.sandbox.zyncro.com/api/v1/rest/users/profile"); Token accessToken = new Token(Paths.ACCESS_KEY, Paths.ACCESS_SECRET); service.signRequest(accessToken, request); Response response = request.send();

...

13

JSON response sample - REST API

{"object":{ "appId":"francoscavuzzo-6387", "fullName":"Franco Scavuzzo", "email":"franco@zyncro.com", "name":"Franco", "lastname":"Scavuzzo", "organizationName":"Zyncro Tech, S.L.", "since":"1283158384316", "isFollowing":false, "isFollowedBy":false, "isFollowingActivity":false, "isFollowedActivityBy":false, "language":"en", "organizationUrn":"syncrum:domain:24078705-7041-4a45-ad1d-32fe4d60ee69", "companyFeedUrn":"syncrum:sharegroup:63e82dde-885b-4f0d-b6b0-8bdcc50ca3c7", "personalFeedUrn":"syncrum:sharegroup:67c4b5c6-f113-4e6c-ac89-ba76993f9388", "personalFilesGroupUrn":"syncrum:sharegroup:379ef9fc-ed31-49ad-9d3d-d2141e68cd4c", "userStatusInfo":{"userStatus":0,"message":"Trabajando","date":"1354527495871"},

…. "canCreateDepartments":false, "isOrganizationAdmin":true, "storageOccupied":"143225271", "storageAssigned":"1048576000",

},"result":"OK“}

14

Play with REST API

Let’s play with the REST API

http://apidocs.sandbox.zyncro.com/

Demo

15

REST API entities

Event Inbox Event Group

Department Member User

16

REST API entities

Organization Invitation Task

Document Document

Version App

17

REST API entities

• All the main entities in API have a unique identifier, normally call URN (unique resource identifier)

• For the attributes that represent date and time, we use UNIX epoch representation in milliseconds

18

REST API entities

An Event represents an activity that has occurred in Zyncro, for example: a user has published a new message, a document has been changed, a new group has been created… Some of the important attributes related with an Event are: • Each event has a unique identifier.

• A date is associated with an event, indicating when it was created. • An event is associated with a group or department, or a private message.

• An event has an author (a user) who has triggered (generated) that event.

• Each event has an type. The most common type is Comment, that is a

message that an user has published. Other types are related with events such as a new member added, some documents uploaded or deleted, etc.

19

REST API entities

• The number of child comments that the event has.

• Information related with the likes the event has received: number of likes and the last user who did it.

• The source of the event gives you information related with the origin of the event. This information is useful for developing integrations; for example we use it to indicate that the event was generated from a device like an Android, iPhone…; or another application Chatter, Yammer…

• The text related with the event, use the attribute comment (plain text) and htmlComment (contains html format text).

• An extra attribute called payload can be used to store information related with the Event in JSON format.

20

REST API entities

A Group is the more general structure in Zyncro, it is a workspace where users share information and communicate. Some of the most important attributes related with a Group are: • Each group has a unique identifier.

• The name and description of the group.

• The owner of the group.

• The number of members the group has.

• Whether the group is public or private

• An extra attribute called payload can be used to store information

related with the Group in JSON format.

21

REST API entities

A Department is similar to a group, but it is only visible to all the organization users. All comments that are published in a department are published in name of the department. Some of the most important attributes related with a Department are: • Each department has a unique identifier.

• The name, description, aboutus (and other properties) of the

department.

• The owner of the department. • An extra attribute called payload can be used to store information

related with the Group in JSON format.

22

REST API entities

A User represents a person registered and using Zyncro. Every user belongs to an organization. Some of the most important attributes related with a User are: • Each user has a unique identifier.

• The name, lastname, email (and other properties) of the user.

• The current language the user has active.

• The identifiers of his Company feed, Personal feed and Personal

group.

• The identifier of his Organization

23

REST API entities

• Some of the permissions in the organization: enable publish in Company feed, enable to create Groups or Departments

If retrieving the full profile of user, extra information is included such as • Skills, experience and education information

• Contact details: address, telephone numbers, mobile • An extra attribute called payload can be used to store information

related with the Group in JSON format.

24

REST API entities

A Member is a user that belongs to a Group or Department with its associated permissions. Some of the most important attributes related with a Member are: • The information included in the User

• The permission of the User in the Group/Department:

• If can publish new messages • If can comment existing messaged • If is owner of the Group/Department • If can add/edit/delete documents • If can invite other users to join • If can add/edit/delete tasks • If can create Zlinks (public links)

25

REST API entities

Organization, every user in Zyncro belongs to one (and only one) organization, that defines the behavior they have in it. Some of the most important attributes related with an Organization are: • Each organization has a unique identifier.

• The name, total users and total storage of the organization

• Basic GUI attributes: header color, header text color, image

• Configuration attributes such as, if tasks are enable, if message can be

deleted, if users can comment on company feed…

26

REST API entities

A Document belongs to a Group or Department. Some of the most important attributes related with a Document are: • Each document has a unique identifier.

• The name and description of the document

• Each event has an type, we have four types of documents:

• File • Folder • External link (to an URL) • Internal link (to another file in other Group/Department)

27

REST API entities

• The date and time of creation and last modification

• The last document version associated with this document

• The number of versions this document has

• The member who created the document

• The member who last modified the document

28

REST API entities

A DocumentVersion represents a version of a document. Some of the most important attributes related with a DocumentVersion are: • Each document version has a unique identifier.

• The version number, size and date time of creation

• The identifier of the group and the document

• The information regarding the member author of this version

29

REST API entities

A InboxEvent is a notification that a user received, generated by an event. Some of the most important attributes related with an Inbox Event are: • Each inbox event has a unique identifier.

• The date and time the inbox event was generated

• The event associated with the inbox event

• Each inbox event has an type, these types are:

• Comment • Like • Follow

30

REST API entities

Invitation Some of the most important attributes related with an Invitation are: • Each invitation has a unique identifier.

• The date time when the invitation was sent

• Information about the user who sent and the user whose received the

invitation

• The state of the invitation (waiting, cancelled, accepted, rejected)

• Each invitation has an type, these types are: • External contact • Group • Follow

31

REST API entities

Task Some of the most important attributes related with a Task are: • Each task has a unique identifier.

• The name and description of the task

• The group identifier where the tasks belongs

• The status of the task (pending or completed)

• The due date of the task

• The user assigned to this task

32

Code samples – REST API

C# (github.com/zyncro/csharp-api-sample)

Java (github.com/zyncro/java-api-sample) PHP (github.com/zyncro/php-api-sample)

Python (github.com/zyncro/python-api-sample)

More to come…

Some samples using the REST API in several programming languages can be found at github.com/zyncro

33

PHP API client

We provide a series of PHP classes that you can use to invoke REST API services from PHP.

OAuth authorization is transparent and you do not have to worry about it, just choose which type to use. https://github.com/zyncro/php-api-client

34

PHP API client - Samples

• Web browser authorization

• External service authorization

$dsf->start(new WallApiService($dsf)); $dsf->controller->zyncroApi->logintype = 'threelegged'; $response = $dsf->controller->getEvents();

$dsf->start(new WallApiService($dsf)); $dsf->controller->zyncroApi->email = $email; $dsf->controller->zyncroApi->pass = $pass; $dsf->controller->zyncroApi->logintype = 'userpass'; $response = $dsf->controller->getEvents();

35

PHP API client - Samples

• Creating a new Group with the API

$dsf->start(new GroupApiService($dsf)); $response = $dsf->controller->createGroup ('A new Group from PHP API', 'The description');

36

PHP API client - Samples

• Publishing a new Message in a Group with the API

• Get Events from a Group with the API

$dsf->start(new WallApiService($dsf)); $response = $dsf->controller->publishInGroup( 'syncrum:sharegroup:01e39c19-313e-404c-9d08-64a047eda89c', 'Hello plain World!', '<p>Hello <span style="font-weight:bold; color:#ff0000;">enriched</span> World</p>');

$dsf->start(new WallApiService($dsf)); $response = $dsf->controller->getGroupEvents( 'syncrum:sharegroup:01e39c19-313e-404c-9d08-64a047eda89c');

37

Zyncro Developers Portal http://developers.zyncro.com

More info

38

WWW.ZYNCRO.COM

Twitter: @zyncro

blog: en.blog.zyncro.com