There is a lot of content available on E-Democracy, and a lot of potential uses of E-Democracy as a communications platform across devices and platforms. However, E-Democracy's underlying platform - GroupServer - does not provide an API for accessing or interacting with groups, topics, and posts.

−

There is a [https://redmine.iopen.net/issues/262 5 year old ticket] on this.

+

=Required or Useful Skills=

−

Ideally, a RESTFUL API would exist that lets developers pull:

+

* '''Python''' - GroupServer is written in Python 2.7

+

* '''Object Orientation''' - Like most web applications, OO is used significantly in GroupServer.

+

* '''Model-View-Controller''' - Likewise, the MVC paradigm is used significantly in GroupServer.

+

* '''Buildout''' - A Python code distribution and development system used by GroupServer. See [[Managing Development in GroupServer and E-Democracy#Buildout]].

+

* '''Git or Mercurial''' - Both distributed version control systems are used in during development. Fortunately, they are very similar. See [[Managing Development in GroupServer and E-Democracy#Code_Repositories]].

+

* '''Zope''' - The framework that GroupServer is built on. Familiarity with any flavor of Zope or its derivatives (i.e. Plone, Grok) will be very helpful. Even more important is familiarity with the [[Zope Component Architecture]].

+

* '''API Creation''' - Since this project is about creating an API, experience in designing and developing APIs will be very helpful.

+

* '''Authentication and Authorization in Zope''' - A big chunk of this project can not be implemented unless a system is in place to authenticate a user and check her authorization via the API. GroupServer make's heavy use of Zope's built in Authentication and Authorization systems, so experience with these will be valuable when working on authentication and authorization on the API.

−

* Group listings

+

=Project Plan=

−

* Topics in a group

+

−

* Posts in a group

+

−

* Posts in a topic

+

−

* User profiles

+

−

and push:

+

To develop a project plan for an API, we are working to answer several questions:

−

* New topics

+

* What data and functionality should be exposed?

−

* New posts

+

* What type of API should be developed (RESTful vs. RPC vs. something else...)?

−

* Changes to user profiles

+

* Should the API conform to some existing standard (i.e. [http://opensocial.org/ OpenSocial])?

+

* What format should the API return data in?

+

* What will the URL(s) be for accessing the API?

+

* Should the API be available to all, or require a token to access?

+

* How should authentication and authorization work?

+

* How should the API code be organized in GroupServer's codebase?

−

The API will provide authentication and provide content based on the authenticated status of the user.

+

None of these questions have been definitively answered yet. But, significant steps have been taken to answer those questions on this page, on this [https://redmine.iopen.net/issues/262 5 year old ticket] (which will be extended as the project's plan solidifies), and on [http://groupserver.org/groups/development/messages/topic/1JYpRDYVRKTGQOFtOgjHAG/ this thread] in GroupServer's Development group.

To support responding to API endpoint requests that submit data, [https://source.iopen.net/groupserver/gs.content.form.api.json/summary gs.content.form.api.json] has been created. It provides two classes - SiteEndpoint and GroupEndpoint - that behave similarly to SiteForm and GroupForm except that they return responses as application/json. All of these classes are based on zope.formlib.

+

+

For general foundational objects in GroupServer (i.e. objects that represent users, groups, posts, etc...), see the [[GroupServer Object and Interface Index]].

+

+

===Endpoint Example===

+

+

For an example of an API that has been build n GroupEndpoint, checkout [https://source.iopen.net/groupserver/gs.group.member.invite.json/summary gs.group.member.invite.json].

+

+

==Proposed Order==

+

+

The first phase of the project should involve providing access to content that does not require authentication. The next phase of the project should allow for a client to authenticate via the API. The third phase of the project should allow for adding content based on the authorization of an authenticated client.

+

+

=What data and functionality should be exposed?=

+

+

This can be divided roughly into:

+

+

* What data should a client be able to retrieve (GET)?

+

* What data should a client be able to write (POST/PUT)?

+

+

==GET==

+

+

Ideally, the API would allow developers pull the following.

+

+

===Groups===

+

+

'''Egg''': edem.group.home.api.json

+

+

A group object should be accessible by a group id and should include:

+

+

* The group's '''name''' (edem.group.home.api.json)

+

* The group's '''url''' (edem.group.home.api.json)

+

* <strike>The group's '''policy''' </strike>

+

* A reference to a list of the group's '''members''' (edem.group.member.list.api.json)

+

* A reference to the group's '''administrators''', '''moderators''', and '''coach''' (edem.group.member.list.api.json)

+

* A reference to a list of the group's '''topics''' (edem.group.messages.topics.api.json)

+

* A reference to a list of the group's '''posts''' (edem.group.messages.posts.api.json)

+

+

A '''list''' of references to publicly visible groups should also be available.

+

+

===Topics===

+

+

'''Egg''': edem.group.messages.topic

+

+

A topic object should be accessible by one of its post's ids and should include:

+

+

* A '''url''' to the topic's page

+

* The '''subject''' of the topic

+

* A reference to a list of '''posts''' in the topic

+

* A list of the '''keywords''' of the topic

+

* A reference to the '''group''' that the topic is in (edem.group.home.api.json)

+

+

A '''list''' of references to publicly visible topics should also be available. There should be the option to specify a group-id to as to retrieve a list of topics of a specific group.

+

+

A note about topic/post ids. To my knowledge, there is no canonical id for a given topic. Instead, a topic can be accessed via the id of any post that is found in that topic.

+

+

===Posts===

+

+

'''Egg''': edem.group.messages.post

+

+

A post object should be accessible by its ID and should include:

+

+

* A '''url''' to the post's page

+

* A reference to the '''topic''' that the post is a part of (edem.group.messages.topic)

+

* A reference to the '''author''' of the post (edem.profile.api.json)

+

* The '''datetime''' of the post

+

* The '''body''' of the post

+

* A list of the '''keywords''' of the post

+

* A list of references to '''files''' attached to the post.

+

+

A '''list''' of references to publicly visible posts should also be available. There should be the option to specify a group-id to as to retrieve a list of posts of a specific group. There should also be the option to retrieve a list of posts for the topic that the post is a part of.

+

+

===Users===

+

+

'''Egg''': edem.profile.api.json

+

+

A user object should be accessible by the user's id and nickname, and should include:

+

+

* A url to the user's '''profile page'''

+

* The '''first''', '''last''', and '''full name''' of the user

+

* A url to the user's '''avatar''' (gs.profile.image.base)

+

* A list of references to '''groups''' that the user is a member of

+

* A list of references to '''posts''' that the user has made

+

+

===Pagination===

+

+

Any of the list retrieval methods should limit the number of results returned, and allow requests to be made for a specific number of results, specific indices, and offsets. Where it makes sense, a request should also be able to specify an order by parameter.

+

+

+

==PUT==

+

+

Assuming we can authenticate a client, we should be able to provide the ability for a client to add content to the site. Upon completion of content addition, the client should receive a simple object indicating the status of the addition (Success, Error, etc...) and either a reference to the successfully added content or an explanation of why the content was not added.

+

+

===Post===

+

+

To add a new post, a client will need to specify:

+

+

* The '''id''' of the topic being added to

+

* The '''body''' of the new post

+

* The '''email address''' the client wants to use to make the post

+

+

Additionally/optionally, a client can also specify:

+

+

* A list of '''files''' to attach to the post

+

+

===Topic===

+

+

To add a new topic, a client will need to specify:

+

+

* The '''id''' of the group the topic is being added to

+

* The '''subject''' of the topic

+

* The '''body''' of the first post of the topic

+

* The '''email address''' the client wants to use to create the topic

+

+

Additionally/optionally, a client can also specify:

+

+

* A list of '''files''' to attach to the first post of the topic

+

+

=How should authentication and authorization work?=

+

+

All of the above GET methods are ok for anonymous users. Like any good API, the GroupServer API should have some means of authenticating requests so that more sensitive information and functionality can be made available via the API to clients that have the appropriate permission.

+

+

Zope already provides a strong system for allowing/disallowing access to content based on the role of the user. The primary challenge then is to allow a client to authenticate with GroupServer/Zope via the API securely. Beyond that, the challenge is how [http://blog.mikepearce.net/2010/08/24/cookies-and-the-restful-api/ strictly one want's to adhere to REST] (assuming the API is RESTFUL). If we are ok with relying on a cookie to store the authentication token, then nothing else really has to be done. If we are not ok with that, then we must allow a token parameter for API requests that the API view can feed to Zope's understanding of the user state.

+

+

Once authentication is implemented, we should go back trough the list of GET methods and determine which ones can provide more information based on the authentication of the client.

Latest revision as of 09:56, 5 October 2013

There is a lot of content available on E-Democracy, and a lot of potential uses of E-Democracy as a communications platform across devices and platforms. However, E-Democracy's underlying platform - GroupServer - does not provide an API for accessing or interacting with groups, topics, and posts.

Zope - The framework that GroupServer is built on. Familiarity with any flavor of Zope or its derivatives (i.e. Plone, Grok) will be very helpful. Even more important is familiarity with the Zope Component Architecture.

API Creation - Since this project is about creating an API, experience in designing and developing APIs will be very helpful.

Authentication and Authorization in Zope - A big chunk of this project can not be implemented unless a system is in place to authenticate a user and check her authorization via the API. GroupServer make's heavy use of Zope's built in Authentication and Authorization systems, so experience with these will be valuable when working on authentication and authorization on the API.

Project Plan

To develop a project plan for an API, we are working to answer several questions:

What data and functionality should be exposed?

What type of API should be developed (RESTful vs. RPC vs. something else...)?

None of these questions have been definitively answered yet. But, significant steps have been taken to answer those questions on this page, on this 5 year old ticket (which will be extended as the project's plan solidifies), and on this thread in GroupServer's Development group.

API Foundation

To support responding to API endpoint requests that submit data, gs.content.form.api.json has been created. It provides two classes - SiteEndpoint and GroupEndpoint - that behave similarly to SiteForm and GroupForm except that they return responses as application/json. All of these classes are based on zope.formlib.

Endpoint Example

Proposed Order

The first phase of the project should involve providing access to content that does not require authentication. The next phase of the project should allow for a client to authenticate via the API. The third phase of the project should allow for adding content based on the authorization of an authenticated client.

What data and functionality should be exposed?

This can be divided roughly into:

What data should a client be able to retrieve (GET)?

What data should a client be able to write (POST/PUT)?

GET

Ideally, the API would allow developers pull the following.

Groups

Egg: edem.group.home.api.json

A group object should be accessible by a group id and should include:

The group's name (edem.group.home.api.json)

The group's url (edem.group.home.api.json)

The group's policy

A reference to a list of the group's members (edem.group.member.list.api.json)

A reference to the group's administrators, moderators, and coach (edem.group.member.list.api.json)

A reference to a list of the group's topics (edem.group.messages.topics.api.json)

A reference to a list of the group's posts (edem.group.messages.posts.api.json)

A list of references to publicly visible groups should also be available.

Topics

Egg: edem.group.messages.topic

A topic object should be accessible by one of its post's ids and should include:

A url to the topic's page

The subject of the topic

A reference to a list of posts in the topic

A list of the keywords of the topic

A reference to the group that the topic is in (edem.group.home.api.json)

A list of references to publicly visible topics should also be available. There should be the option to specify a group-id to as to retrieve a list of topics of a specific group.

A note about topic/post ids. To my knowledge, there is no canonical id for a given topic. Instead, a topic can be accessed via the id of any post that is found in that topic.

Posts

Egg: edem.group.messages.post

A post object should be accessible by its ID and should include:

A url to the post's page

A reference to the topic that the post is a part of (edem.group.messages.topic)

A reference to the author of the post (edem.profile.api.json)

The datetime of the post

The body of the post

A list of the keywords of the post

A list of references to files attached to the post.

A list of references to publicly visible posts should also be available. There should be the option to specify a group-id to as to retrieve a list of posts of a specific group. There should also be the option to retrieve a list of posts for the topic that the post is a part of.

Users

Egg: edem.profile.api.json

A user object should be accessible by the user's id and nickname, and should include:

A url to the user's profile page

The first, last, and full name of the user

A url to the user's avatar (gs.profile.image.base)

A list of references to groups that the user is a member of

A list of references to posts that the user has made

Pagination

Any of the list retrieval methods should limit the number of results returned, and allow requests to be made for a specific number of results, specific indices, and offsets. Where it makes sense, a request should also be able to specify an order by parameter.

PUT

Assuming we can authenticate a client, we should be able to provide the ability for a client to add content to the site. Upon completion of content addition, the client should receive a simple object indicating the status of the addition (Success, Error, etc...) and either a reference to the successfully added content or an explanation of why the content was not added.

Post

To add a new post, a client will need to specify:

The id of the topic being added to

The body of the new post

The email address the client wants to use to make the post

Additionally/optionally, a client can also specify:

A list of files to attach to the post

Topic

To add a new topic, a client will need to specify:

The id of the group the topic is being added to

The subject of the topic

The body of the first post of the topic

The email address the client wants to use to create the topic

Additionally/optionally, a client can also specify:

A list of files to attach to the first post of the topic

How should authentication and authorization work?

All of the above GET methods are ok for anonymous users. Like any good API, the GroupServer API should have some means of authenticating requests so that more sensitive information and functionality can be made available via the API to clients that have the appropriate permission.

Zope already provides a strong system for allowing/disallowing access to content based on the role of the user. The primary challenge then is to allow a client to authenticate with GroupServer/Zope via the API securely. Beyond that, the challenge is how strictly one want's to adhere to REST (assuming the API is RESTFUL). If we are ok with relying on a cookie to store the authentication token, then nothing else really has to be done. If we are not ok with that, then we must allow a token parameter for API requests that the API view can feed to Zope's understanding of the user state.

Once authentication is implemented, we should go back trough the list of GET methods and determine which ones can provide more information based on the authentication of the client.