Swagger

Swagger is a specification for describing REST APIs. The main aim of Swagger is to provide a REST API definition format that is readable by both machines and humans.

You can think of two entities in a REST API: One the provider of API, and another the client using the API. Swagger essentially covers the gap between them by providing a format that is easy to use by the client and easy for the provider to define.

If not using Swagger, one would most certainly be creating the API first, writing the documentation (human-readable) with it. The client developer would read the documentation and use APIs as required. With Swagger, the specification can be considered as the document itself, helping both the client developer and the provider.

Here’s an example spec I wrote for our GET APIs at Organizer Server: https://gist.github.com/shivamMg/dacada0b45585bcd9cd0fbe4a722eddf

The format, although readable doesn’t really look what a client developer would be asking for.

Remember that the format is machine readable? What does it mean exactly?

Since the Swagger spec is a defined format, the provider can document it and people can write programs that understand the Swagger specification. Swagger itself comes with a set of tools (http://swagger.io/tools/) that use Swagger definitions created by the API provider to create SDKs for the clients to use.

Swagger-UI

One of our most used tools at our server is the Swagger UI (http://swagger.io/swagger-ui/).

It reads an API spec written in Swagger to generate corresponding UI that people can use to explore the APIs. Every API endpoint can have responses and parameters associated with it. For instance our Event endpoint at Server (“/events/:event_id”).

You can see how the UI displays the Model Schema, required parameters and possible response message.

Screenshot from 2016-06-07 19:08:21

Apart from documentation, Swagger UI provides the “Try it out!” tool that lets you make requests to the server for the corresponding API. This feature is incredibly useful for POST requests. No need for long curl commands in the terminal.

Here’s the Swagger config from our demo application: https://open-event.herokuapp.com/api/v2/swagger.json

The Swagger UI for this config can be found at https://open-event.herokuapp.com/api/v2

The UI for the example spec (gist) I linked before can be browsed here.

Swagger-js

https://github.com/swagger-api/swagger-js

Swagger-js is JS library that reads an API spec written in Swagger and provides an interface to the client developer to interact with the API. We will be using Swagger-js for Open Event Webapp.

Here’s an example to show you how it works. Let’s say the following endpoint returns (json) a list of events.

/events

The client developer can create a GET request and render the list with HTML.

$.getJSON("http://example.com/api/v2/events", function(data) {

  var events = "";
  $.each(data, function(i, event) {
    events += "<li id='event_" + i + "'>" + event.name + "</li>";
  });

  $("ul#events").html(events);
});

What if the provider moves the endpoint to “/event/all”? The client developer would need to change every instance of the URL to http://example.com/event/all.

Let’s now take the case of Swagger-js. With Swagger-js the client developer would essentially be writing programs to interact with the API Swagger spec defined by the provider, instead of directly consuming the API.

window.client = new SwaggerClient({
    url: "http://example.com/api/v2/swagger.json",
    success: function() {
      client.event.getEvents({
        responseContentType: 'application/json'
      }, function(data) {

        /* Create `events` string same as before */

        $("ul#events").html(events);
      });
    }
  });

 

The APIs at the Organizer server are getting more complex. Swagger helps in keeping the spec well defined.

That’s all for now. Hope you enjoyed the read.

Continue ReadingSwagger

REST API Authentication in Flask

Recently I had the challenge of restricting unauthorized personnel from accessing some views in Flask. Sure the naive way will be asking the username and password in the json itself and checking the records in the database. The request will be something like this-

{
	"username": "open_event_user",
	"password": "password"
}

But I wanted to do something better. So I looked up around the Internet and found that it is possible to accept Basic authorization credentials in Flask (sadly it isn’t documented). For those who don’t know what Basic authorization is a way to send plain username:password combo as header in a request after obscuring them with base64 encoding. So for the above username and password, the corresponding header will be –

{
	"Authorization": "Basic b3Blbl9ldmVudF91c2VyOnBhc3N3b3Jk"
}

where the hashed string is base64 encoded form of string “open_event_user:password”.

Now back to the topic, so the next job is to validate the views by checking the Basic auth credentials in header and call abort() if credentials are missing or wrong. For this, we can easily create a helper function that aborts a view if there is something wrong with the credentials.

from flask import request, Flask, abort
from models import UserModel

app = Flask(__name__)

def validate_auth():
	auth = request.authorization
	if not auth:  # no header set
		abort(401)
	user = UserModel.query.filter_by(username=auth.username).first()
	if user is None or user.password != auth.password:
		abort(401)

@app.route('/view')
def my_view():
	validate_auth()
	# stuff on success
	# more stuff

This works but wouldn’t it be nice if we could specify validate_auth function as a decorator. This will give us the advantage of only having to set it once in a model view with all auth-required methods. Right ? So here we go

def requires_auth(f):
	@wraps(f)
	def decorated(*args, **kwargs):
		auth = request.authorization
		if not auth:  # no header set
			abort(401)
		user = UserModel.query.filter_by(username=auth.username).first()
		if user is None or user.password != auth.password:
			abort(401)
		return f(*args, **kwargs)
	return decorated

@app.route('/view')
@requires_auth
def my_view():
	# stuff on success
	# more stuff

I renamed the function from validate_auth to requires_auth because it suits the context better.

At this point, the above code may look perfect but it doesn’t work when you are accessing the API through Swagger web UI. This is because it is not possible to set base64 encoded authorization header from the swagger UI. For those who are wondering “what the hell is swagger”, I will define Swagger as a tool for API based projects which creates a nice web UI to live-test the API and also exports a schema of the API that can be used to understand API definitions.

Now how do we get requires_auth to work when a request is sent through swagger UI ? It was a little tricky and took me a couple of hours but I finally got it. The trick therefore is to check for active sessions when there are no authorization headers set (as in the case of swagger UI). If an active session is found, it means that the user is authenticated. Here I would like to suggest using Flask-Login extension which makes session and login management a child’s play. Always use it if your flask project deals with login, user accounts and stuff.

Now back to the task in hand, here is how we can set the requires_auth function to check for existing sessions.

from flask import request, abort, g
from flask.ext import login

def requires_auth(f):
	@wraps(f)
	def decorated(*args, **kwargs):
		auth = request.authorization
		if not auth:  # no header set
			if login.current_user.is_authenticated:  # check active session
				g.user = login.current_user
				return f(*args, **kwargs)
			else:
				abort(401)
		user = UserModel.query.filter_by(username=auth.username).first()
		if user is None or user.password != auth.password:
			abort(401)
		g.user = user
		return f(*args, **kwargs)
	return decorated

Pretty easy right !! Also notice that I am saving the user who was currently authenticated in flask’s global variable g. Now the authenticated user can be accessed from views as g.user. Cool, isn’t it ? Now if there is a need to add a more secure form of authorization like ‘Token’ based, you can easily update therequires_auth decorator to get the same results.

I hope this article provided valuable insight into managing REST API authorizations in Flask. I will keep posting more awesome things I learn in my GSoC journey.

That’s it. Sayonara.

 

{{ Repost from my personal blog http://aviaryan.in/blog/gsoc/auth-flask-done-right.html }}

Continue ReadingREST API Authentication in Flask

Bower Dependency & Configure .bowerrc to use Proxy

2 weeks into GSOC 2016, the project has really started to grow at a rapid pace. There have been a lot of issues related to UI as well as other different bugs. As we use more and more libraries for the user interface of the dashboard, we added bower dependencies to install the libraries.

Why Use Bower?

Some of the benefits of using bower dependencies are:

  • Simplify what might be called declarative dependency management; i.e. you declare your dependencies in bower.json so that other things can determine them easily
  • No need to commit dependencies to version control
  • Semantic versioning is used to help define a range of acceptable versions for a dependency, which makes it easy to update to newer versions within the defined range
  • No need to locate various builds (debug, minified, etc)
  • Simple to use different builds of a dependency for dev vs. prod
  • Bower lets you easily search and install libraries even locking to a specific version. Bower makes it easy to list and update dependencies.
  • You can distribute the bower.json file and everyone can get up to speed with a simple “bower install”

Prerequisites

There are some things you’ll need before you can start working with Bower:

  • The command line.
  • Node and NPM.
  • Git.
  • Global Installation. .

To install Bower globally:

$ npm install -g bower

bower.json

The `bower.json` file looks a lot like Node’s `package.json`. It is a manifest file that allows you to specify the various packages you want to download along with their version number and various features. This is how the `bower.json` looks for the open-event-orga-server project.Screenshot from 2016-06-04 05:25:08.png

.bowerrc

The `.bowerrc` file can be seen as a configure file for bower which dictates various rules to it. Though mostly this file is ignored and is used mainly to specify the directory where the libraries are to be installed instead of the default `bower_components`, however it can be used to do a lot more than that.

Screenshot from 2016-06-04 05:29:50.png

For example, one of the biggest problem you might face while installing using bower is if your organization/institute has a proxy network through all network connections pass. In that case bower install might not be able to install the libraries. However we can configure the .bowerrc to work via proxy.

Configure .bowerrc to use Proxy

To use http proxy, we can add 2 properties to .bowerrc which will make bower search and install libraries using the proxy. The properties are “proxy” and “https-proxy”. This 2 properties dictate that both http:// and https:// links are to be searched via the proxy. So, to make this settings, we can configure the .bowerrc something like this:
Screenshot from 2016-06-04 05:35:13.png

This should then fix your problem of proxy and will install your libraries as desired.

Continue ReadingBower Dependency & Configure .bowerrc to use Proxy

Transmitting response from a Web page to a server.

{ Re-post from my Medium Post }

My project has pivoted from a standalone android app to a Web page that will generate a custom app for an event organizer’s use.

Read up here on what my project actually is.

So obviously some changes at the server are to be made to make this possible.

How are you planning to do it?

First of we started by providing a Web page that the organizers can use to submit information about the app they need to be built like the App’s name, the link to the API (for fetching the json files) and their email address (for mailing them the apk once it’s generated).

The HTML file for the same can be found here.

Some changes to the Travis build should also be made so that it can use this data for building.

From there on, the details submitted by them will be converted by a json object (using javascript) and further send to the open event server via a POST request where it will be written to a database.

We will be able to fetch this file from the database by the following link

openevent.com/api/v2/customapps/id.

Simultaneously one Travis build will also be trigger using the API that will auto build the latest commit, taking the modified json file data provided by the orga-server.

This configuration will be provided to Travis while the build time.

Cool, any difficulties yet!

One of the main challenges that we are facing is manually triggering the Travis build.

We can do this via the Travis API but that’s still in beta and also we are getting our head around on how to implement it.

I also had a tough time learning javascript and HTML for making the Web page and then I also have to read up on sending a POST request to the server via Ajax.

It’s a bit tough, but should be fun.

So, that was all for now, see you next week and all the best for your projects.✌

Continue ReadingTransmitting response from a Web page to a server.

Open Event: Planning the Scheduler UI

{ Repost from my personal bloghttps://blog.codezero.xyz/planning-the-scheduler-ui/ }

In the first phase of the GSoC coding period, Saptak Sengupta and myself have been working on the Scheduler UI.

The Scheduler UI would allow the organizers to graphically schedule/manage the sessions in their conference/event.

Event-Organizer by Josh Greco has been a major inspiration for the timeline design. The css styles have been borrowed from that project.

After some research, we have decided to use the interact.js javascript library for implementing drag-drop and resizing functionality to the project and lodash for array/collection manipulations and for some useful utility functions.

The following tasks have been formulated:

  • Drag-and-drop interface to add session blocks into a timeline
  • Resize sessions to change time
  • load live data from the server using the API
  • Handle session clashes within a track properly
  • Add Track button that opens up a modal to add a track.
  • Search option for unscheduled sessions
  • Save each session change/update using the API
  • Option to Export timeline as pdf
  • Option to export timeline/calendar as iCal

An umbrella issue (#349) has been created in the open-event-orga-serverrespository to track the progress. There will be a separate issue created for each task when that task is being worked upon and the same would be referred to in the umbrella issue.

We are targeting GSOC 2016: Milestone 4 (Due by June 12, 2016) to finish the Scheduler UI and we are confident that we’ll be able to reach our target. *fingers-crossed* :sweat_smile:

To know more about the Scheduler UI, read Enhancing the Open Event Server: Scheduler UI.

Continue ReadingOpen Event: Planning the Scheduler UI

Rest-API implementation in the flask Open Event Application

These days are getting so worked up. For the first time in my life, I have to attend to around 40 emails a day. If you count the replies with them, it will be well over 150. Things have got so busy.

To start off, our project is called Open Event. Open Event is a software suite to help people manage events, summits, conferences etc with relative ease. The organizers will have the power to manage sessions, speakers, tracks and schedule from a clean and user-friendly interface.

They can auto-tweet the sessions, generate a google calendar, post to social networks and do other fancy things with just a click of the button. Then there are android apps for both attendees and organizers. The organizers can use the app to manage the event whereas the attendees can use it to get details about upcoming events, give reviews, vote on stuff and so on. From the web interface, rich data can be shown about the event like the number of sessions, distinct speakers, schedule and other statistics. In other words, a website can be easily generated for the event. Apart from that, the project will feature a rich API which can used by other services to build up on it.

My part

Me and @shivamMg are responsible for the REST API part of the project. The plan is to build a full-proof API that will cover the entire scope of the application.

We have started the work using Flask-Restplus as the framework. The GET API part has been done. Now what is needed is to add the PUT, POST and DELETE verbs.

We will soon get to it and plan to have a basic version ready before the midterm (26th June). Once midterm is done, we will work on enhancing the API, finding and fixing bug cases, writing docs and improving overall project quality.

This is getting so much fun. The next 3 months will be full of heavy coding. Probably my GitHub streak will cross 100 days :stuck_out_tongue_winking_eye:. I am learning so much with every day that passes.

As many as 10 people are working on the Open Event project this summer. Working in such a big group project will be a new experience for me and I am so glad to be a part of it.

That’s all for now. See ya !!

{{ Repost from my personal blog http://aviaryan.in/blog/gsoc/so-it-begins.html }}

Continue ReadingRest-API implementation in the flask Open Event Application

Enhancing the Open Event Server: Scheduler UI

{ Repost from my personal blog @ https://blog.codezero.xyz/enhancing-open-event-scheduler-one/ }

The community bonding period went pretty well. Worked on the OpenTechSummit 2016‘s website. Fixed a few issues. Got to know the team. :smile:

Now comes the coding period which started yesterday (23rd May 2016).
In the first phase, I (Niranjan Rajendran) will be primarily working on creating a Scheduler tool for each event. Saptak Sengupta and myself will be working on this.

The Scheduler would allow the organizers to graphically schedule/manage the sessions in their conference/event. The proposed features for the Scheduler are:

  1. Drag-and-drop sessions into tracks on a timeline.
  2. Change the timings of the sessions by resizing the sessions’ element on the timeline.
  3. Create a new event by dragging a time period on the timeline.
  4. Create new tracks.
  5. Switch between timelines of the different days of the event.
  6. Load existing sessions from the database into the timeline.
  7. Print the timeline or convert it into a PDF file.
  8. Export the schedule in different formats such as iCalendar.

The scheduler UI would not be practical on small screens (Mobile phones) and would be hard to use. So, we will be thinking of some alternative – a simpler interface for smaller screens.

Continue ReadingEnhancing the Open Event Server: Scheduler UI

Organizer Server and REST APIs

The Open Event Organizer Server is a server application written in Flask. It provides an admin interface for the organizers of events to manage events and related services like Sessions, Tracks, etc. Additionally it provides GET APIs for developers to read data from the server. These APIs are consumed by the Open Event Webapp and Android Client to display details to the users. The existing APIs could only fetch data. My is to create REST APIs that write data to the server.

Developers are divided into groups with every group handling one aspect of the project. Avi Aryan and I would be working on REST APIs. Currently I’m working on porting the existing GET APIs to newer spec. Justin decided on our stack and technologies we would be working with (link). We are using Flask-Restplus extension for building APIs.

The write API is not going to be the only big change to the server. The new authorization system is also going to change a lot. It would include more user roles, with each of them having different set of permissions. Apart from the Administrator and Organizer, a user can be:

  • Attendee
  • Moderator
  • Speaker
  • Track Organizer

Other changes to User Management are mentioned in the docs.

Besides these, adding support for OAuth 2.0 is also on the list. This would let users sign up through Social Media platforms.

I had thought of a possible work flow for my group.

  1. Port existing GET APIs with newer spec on Flask-Restplus.
  2. Add the user roles mentioned above to the authorization system. A user role defines what type of services a user has access to. For example, an Attendee has write access to feedback and rating system for Sessions but he does not have permissions to create or modify Tracks. This needs to be done before creating write (POST/PUT/DELETE) APIs, so that access to services can be defined according to the user roles. The GET APIs are public and do not require any such permissions.
  3. Create write APIs.
  4. Set up user authentication system to register and sign in users.
  5. Add support for OAuth 2.0.

Many of these changes require other changes to the server. Like the feedback and rating system for Attendees has not been implemented yet and would first require definitions for its database models. Existing models would also require changes. A lot of work to do.

I have previously worked with Python and Django. This project brings a lot of new stuff for me. Python2, Flask, Swagger and RESTful APIs. DukeJustin and Mario are going to be mentors for the Organizer Server. All in all, this summer is going to be an exciting one 😀.

About Me:

I’m Shivam, a 3rd year Computer Engineering student from College of Technology, Pantnagar. This is my first attempt at GSOC and I’m grateful to FOSSASIA for accepting my proposal. I started out with FOSSASIA by contributing to their Open Source projects.

Continue ReadingOrganizer Server and REST APIs

Enhancing Open Event Organizer Server

Today, the coding phase of GSoC 2016 starts and marks the beginning of the implementation of all the prototypes and brainstormed ideas. Open Event Organizer Server as explained previously is the backend server for the organizers to create events, sessions, mark tracks, add social links, date/time, etc. It acts as the dashboard for creating data which then gets displayed through the client side apps , i.e open event webapp and android app. Sounds perfect. But as we know there is always scope for improvement.

So, this year we focus on making the server even better. The purpose is not only to make it more useful and powerful with added features but also to make it intuitive for the organizer so that the app can be used to its fullest benefits. A lot of brainstorming by a lot many students and mentors of this project have resulted in a final protoype to be implemented with some features and a better UI.

Some of the features that we have decided to add are:

  • API authentication to provide proper permissions. This helps in improving the overall security.
  • Oauth authentications. No more registration required. The organizer can straightaway use their google, fb and other login credentials to login and create events.
  • Social Links. The organizer can now add social links for their events such as google plus event link, facebook event link, hashtag values, etc.
  • Schedule UI. Now the organizer can directly add the events in calendar and get notified on that particular day. One can also export it in different formats.
  • Overall UI Improvement. We aim to make the UI much more intuitive and easier to use for the organizer so that all the features can be used to its fullest advantage.

This is briefly the aim for making open event organizer server bigger, better and more useful. With this aim, we start our coding today and try to provide a great product by the end of GSoC 2016. A product so good that every event organizer starts using this. Looking forward to making it a success.

Continue ReadingEnhancing Open Event Organizer Server

Wrapping up our first steps – Event Server, Material Design, Daily Scrum

The Event Organizer application has already the basic features and we can move to apply more advanced feature. But let explain me, what me and my friends have done recently.

Our application is already able to manage conferences and events. An owner can edit and change events in the way he/she wants to. And we have two version of this app for websites and for mobile phones(Android). The orga serv which I prepared share Json API to both Android and Web app. I guess it is really comfortable solution because it enables to share date between web and mobile app. Our app’s template style is based on material bootstrap, the same is used by Arnav in his application. It is very flat design.

Zrzut ekranu 2015-07-06 o 22.58.07
First Version of Open EVent Menu Bar

What I really like during this term is daily scrum, where we can share what we have already done, what are we going to do next, and what were the obstacles. Because of it, we can easily be in touch and avoid duplicating our work. We can also discuss and quickly choose the most useful solution. Duke and Mario accompany us and as always were ready to help with any trouble.

Arnav and Manan also organized a conference on their university. Many students were invited and discussed about taking part in open source projects. I regret not to having taken part in it, but India is so far from my country, that I could not get there.

I hope that the starting up part of this project will be also so developing and exciting, and we will finish it with a huge success. And all of us will be very proud, learn many new things, and improve our experience.

In the nearest future Arnav, Duke and me are going to create three environments: staging, production, and development. It helps us to organize our work. I am sure that we manage to do it.

Ok, so stay tuned. “Show must go on”! We don’t stop working! 😉

Continue ReadingWrapping up our first steps – Event Server, Material Design, Daily Scrum