The Codex of Business Writing Software for Real-World Solutions 2.pptx
Zyncro rest api feb 2013
1. Social Networks
Your Enterprise Social Network For Enterprises
Developing using the REST API
1
2. Agenda
REST API overview
REST API services
OAuth authorization
Let’s play with the API
REST API entities
PHP API client
2
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.
3
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.
4
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.
5
6. REST API - Use
We are using the REST API, for example, in these integrations and native apps
6
7. Play with REST API
Show me the money!
http://apidocs.sandbox.zyncro.com/
7
8. REST API services
• Manage the organization configuration
Organization services • Manage organization's users (add/edit/remove)
/api/v1/rest/organization • Edit organization properties
• Only admin users can have access to these services
• Manage user profiles
Users services • Access follower/following user lists
/api/v1/rest/users • Edit user profile, change user’s profile image
• Follow/Unfollow users
Microblogging and Activity • Access and publish in all microblogging, including
Stream & Inbox services Personal feed, Corporate feed, Department feeds,
Private messages and Messages from Groups
/api/v1/rest/wall • Access user's inbox events and notifications
• Create new groups
Groups services • Download, edit, and upload documents to groups
/api/v1/rest/groups • Manage group members, folders and files
• Join/leave open groups
8
9. REST API services
• Create new departments
Departments services • Download, edit, upload documents in departments
/api/v1/rest/departments • Manage department members, folders and files
• Follow/unfollow departments
• Manage invitations.
Invitations services
• Send, accept, decline invitations
/api/v1/rest/invitations
• Access the list of pending invitations
• Create new tasks.
Tasks services
• Edit task and access to the tasks of groups
/api/v1/rest/tasks
• Access to the list of tasks
ZyncroApps Services • Manage apps (add/edit/remove)
/api/v1/rest/apps • Enable/disable apps
9
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
10
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!
11
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();
...
12
16. REST API entities
Organization Invitation Task
Document
Document App
Version
16
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
17
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.
18
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.
19
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.
20
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.
21
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
22
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.
23
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)
24
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…
25
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)
26
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
27
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
28
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
29
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
30
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
31
32. Code samples – REST API
Some samples using the REST API in several programming languages
can be found at github.com/zyncro
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…
32
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
33
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');
35
36. PHP API client - Samples
• Publishing a new Message in 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>');
• Get Events from a Group with the API
$dsf->start(new WallApiService($dsf));
$response = $dsf->controller->getGroupEvents(
'syncrum:sharegroup:01e39c19-313e-404c-9d08-64a047eda89c');
36
37. More info
Zyncro Developers Portal
http://developers.zyncro.com
37
