me-api Documentation Release v0.1.0

lord63

February 20, 2016

Contents

1 User’s Guide 1 1.1 Introduction...... 1 1.2 Qucikstart...... 2 1.3 Integrate with your sites...... 2 1.4 Gallery: live demos...... 6

2 Developer’s Guide 7 2.1 Contribute to me-api...... 7 2.2 Develop a new middleware...... 8

3 Additional Notes 11 3.1 Authors...... 11

i ii CHAPTER 1

User’s Guide

1.1 Introduction

Me-api is a personal API built on python and flask that allows for extensible integrations. It’s a python port of the original Node.js version me-api. It is called me-api, you can build a personal website with it. With me-api, you can fetch your photos on instagram, get your tweets from twitter, show you code activity on github, list your blog post from medium, and etc.

1.1.1 Data Representation

There are two main json files: me.json and modules.json. me.json: { "name":"lord63", "join_github":"20 Aug 2013" }

It’s all about you. Your name, your age, your hobbies, you can add anything about youself. You’ll see them on the root path “/” once you’ve configured me-api. modules.json: { "modules":{ "medium":{ "path":"/blog", "data":{ "me":"@username" } }, "github":{ "path":"/code", "data":{ "me":"username" } } } }

1 me-api Documentation, Release v0.1.0

Just as its name, it has many modules. Using custom middleware, you can attach the data pulled from various social media feeds to specific endpoints in your API. “path” is the endpoint which you want to host the middleware on, “data” contains some other info so that we can fetch data from the site(some may need authentication).

1.2 Qucikstart

This page gives your a guide for how to set up the basic configuration for me-api. Head over to Integrate with your sites for further information.

1.2.1 Install from Souce Code

Clone the fresh code and go into the directory: $ git clone [email protected]:lord63/me-api.git $ cd me-api

Install the requirements(recommend using virtualenv): $ virtualenv venv $ source venv/bin/activate (venv)$ pip install -r requirements/requirements.txt

1.2.2 Configure Me-api

Init the json files: (venv)$ python generate init

Answer several questions according to the prompt. It will help you generate me.json and modules.json in the me_api/me_api/ folder. When choosing middlewares, I suggest using github for demo purpose, very easy to set up, only username required. Note that ‘path’ should have a leading slash(e.g. ‘/github’), and ‘username’ in the prompt have an ‘@’ should have an ‘@’. Once generated the config file, now you have a very simple demo, run it using: (venv)$ python manage.py runserver

Open ‘localhost:5000’ in your broswer and take a look.

1.3 Integrate with your sites

1.3.1 Douban

Short Introduction about Douban

Douban (Chinese: ; pinyin: Dòubàn), launched on March 6, 2005, is a Chinese SNS website allowing registered users to record information and create content related to film, books, music, and recent events and activities in Chinese cities. 1 1 https://en.wikipedia.org/wiki/Douban

2 Chapter 1. User’s Guide me-api Documentation, Release v0.1.0

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host douban on “/douban” path. 1. Go to the Douban Apps page and create a new app. Make sure that the callback uri equals to “http://api.foo.com/douban/login/redirict” (site + path + ‘/login/redirect’). 2. Go to the app you just created, take down the API Key and Secret. 3. Go ‘test user’ page in you app, add your douban account as a test user. 4. Back to me-api, add the douban middleware to your config file: $ python generate add

then choose douban and input the data. 5. Go to “http://api.foo.com/douban/login”, authorize your app to get the access_token. 6. Take down the access_token and fill it in our config file. 7. Restart the server, go to “http://api.foo.com/douban” and have a check.

1.3.2 Github

Short Introduction about Github

GitHub is a web-based Git repository hosting service, which offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features.As of 2015, GitHub reports having over 9 million users and over 21.1 million repositories, making it the largest code hoster in the world. 2

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host github on “/code” path. 1. Add github middleware to your config file: $ python generate add

then choose github and follow the prompt. 2. That’s all! Restart the server, go to “http://api.foo.com/code” and have a check.

1.3.3 Instagram

Short Introduction about Instagram

Instagram is an online mobile photo-sharing, video-sharing and social networking service that enables its users to take pictures and videos, and share them on a variety of social networking platforms, such as Facebook, Twitter, Tumblr and Flickr. 3 2 https://en.wikipedia.org/wiki/GitHub 3 https://en.wikipedia.org/wiki/Instagram

1.3. Integrate with your sites 3 me-api Documentation, Release v0.1.0

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host instagram on “/instagram” path. 1. Go to the Instagram Clients page and create a new client. Make sure that the Redirect URI equals to “http://api.foo.com/instagram/login/redirict” (site + path + ‘/login/redirect’). 2. Go to the app you just created, take down the Client ID and Client Secret. 3. Back to me-api, add the instagram middleware to your config file: $ python generate add then choose instagram and input the data. 4. Go to “http://api.foo.com/instagram/login”, authorize your app to get the access_token. 5. Take down the access_token and fill it in our config file. 6. Restart the server, go to “http://api.foo.com/instagram” and have a check.

1.3.4 Keybase

Short Introduction about Keybase

Well, Keybase is a website, but it’s also an open source command line program. Let’s walk through a terminal example, which illustrates what Keybase does. All of this can be embedded into other software, written by anyone. 4

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host keybase on “/keybase” path. 1. Add keybase middleware to your config file: $ python generate add then choose keybase and follow the prompt. 2. That’s all! Restart the server, go to “http://api.foo.com/keybase” and have a check.

1.3.5 Medium

Short Introduction about Medium

Medium is a blog-publishing platform. The platform has evolved into a hybrid of non-professional contributions and professional, paid contributions, an example of social journalism. 5

Integrate Guide

WARNING 4 https://keybase.io/ 5 https://en.wikipedia.org/wiki/Medium_%28service%29

4 Chapter 1. User’s Guide me-api Documentation, Release v0.1.0

UPDATED on 2016-02-20: the way to fetch the lastest posts can’t work any more, please help. Related discussions are at issue #8.

Let’s assume that your api site is “http://api.foo.com”, you host medium on “/medium” path. 1. Add medium middleware to your config file: $ python generate add then choose medium and follow the prompt. 2. That’s all! Restart the server, go to “http://api.foo.com/medium” and have a check.

1.3.6 Stack Overflow

Short Introduction about Stack Overflow

Stack Overflow serves as a platform for users to ask and answer questions, and, through membership and active participation, to vote questions and answers up or down and edit questions and answers. The website features questions and answers on a wide range of topics in computer programming. 6

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host stack overflow on “/stackoverflow” path. 1. Go to the Stack Overflow Apps page and create a new app. Make sure that the OAuth Domain covers “http://api.foo.com/stackoverflow/login/redirict” (site + path + ‘/login/redirect’). In this example, you can set it as “api.foo.com”. 2. Go to the app you just created, take down the Client Id, Client Secret and Key. 3. Back to me-api, add the stack overflow middleware to your config file: $ python generate add then choose stackoverflow and input the data. 4. Go to “http://api.foo.com/stackoverflow/login”, authorize your app to get the access_token. 5. Take down the access_token and fill it in our config file. 6. Restart the server, go to “http://api.foo.com/stackoverflow” and have a check.

1.3.7 Twitter

Short Introduction about Twitter

Twitter (/twtr/) is an online social networking service that enables users to send and read short messages called “tweets”. 7 6 https://en.wikipedia.org/wiki/Stack_Overflow 7 https://en.wikipedia.org/wiki/Twitter

1.3. Integrate with your sites 5 me-api Documentation, Release v0.1.0

Integrate Guide

Let’s assume that your api site is “http://api.foo.com”, you host twitter on “/twitter” path. 1. Go to the Twitter Apps page and create a new app. 2. Go to the app you just created, click the ‘Keys and Access Tokens’ tab, take down the Consumer Key (API Key), Consumer Secret (API Secret), Access Token and Access Token Secret. 3. Back to me-api, add the twitter middleware to your config file: $ python generate add then choose twitter and input the data. 4. Restart the server, go to “http://api.foo.com/twitter” and have a check.

1.4 Gallery: live demos

Here are some live demos which are powered by me-api. If you’re using me-api and you want to share it with others, feel free to send a pull request and I’ll be happy to merge it for sure. Don’t be shy ;) Also please note that me-api is totally under your control, you can choose things you want to share with us. So if there’s something about your privacy, and you don’t want others know that, then don’t use that middleware or keep your site as a secret. And you have the right to remove your site here at any time without any reason, I promise. The following are a bunch of sites powered by me-api, sorted by the time for sending the pull request.

6 Chapter 1. User’s Guide CHAPTER 2

Developer’s Guide

2.1 Contribute to me-api

Please do contribute! As an open source project, me-api welcomes many kinds of contribution. I’d like to say thanks to all of those who helped me-api. You can: • Involve in github issues, help answer questions and leave your opinions. • Review the pull requests and the existing code, help us improve it. • Send pull requests and patches. • Report bugs with detailed information so that we can reproduce them. • Let more people know me-api if you think me-api is not bad :p • Any other way that you think it is good for me-api. But, to make this project easy to maintain and stay healthy, here are some guidelines.

2.1.1 Send A Pull Request

• Fork the repo and then clone the code. • Checkout a new git branch(e.g. add-foo-middleware) • Install the requirements if necessary: $ virtualenv venv $ source ./venv/bin/activate (venv)$ pip install -r dev-requirements.txt

• Begin your work and once finished, make sure that the tests passed: $ make tests

• It’s time to make a pull request. Thanks again!

2.1.2 Develop Middlewares

Head over to Develop a new middleware

7 me-api Documentation, Release v0.1.0

2.2 Develop a new middleware

Since many websites use OAuth2 for their APIs, many middlewares seems very similar to each other. If you’ve created a middleware, it should be easy for you to create another one. You can take a look at douban.py and stackoverflow.py. For these don’t need access token, can’t be esay any more. Take a look at github.py, keybase.py and medium.py.

2.2.1 Build a universal middleware

This chapter is for those public service, such as Instagram, github and etc. I’ll take instagram as an example to show you how to develop a universal middleware.

1. Add the New Middleware

Add a new middleware in me-api/me-api/middlewares folder, in this example, we add a new middleware named instagram: instagram.py. I’ll take this one into details: #!/usr/bin/env python #-*- coding: utf-8 -*- from __future__ import absolute_import

# Import modules you need. import os import requests from flask import Blueprint, jsonify, request, redirect

# Import cache, config and help utils. from me_api.cache import cache from me_api.middleware.utils import (MiddlewareConfig, token_required, reject_duplicated_auth)

# Get configuration from our `modules.json`. config= MiddlewareConfig('instagram') # Our main blueprint. instagram_api= Blueprint('instagram', __name__, url_prefix=config.path)

# Get information once we have access token, remember to set # a proper timeout for the middleware cache. @instagram_api.route('/') @cache.cached(timeout=60*60) @token_required(config) def index(): pass

# Get authorization_code. @instagram_api.route('/login') @reject_duplicated_auth(config) def authorization(): pass

# Get access token we need. @instagram_api.route('/login/redirect')

8 Chapter 2. Developer’s Guide me-api Documentation, Release v0.1.0

def get_access_token(): pass

2. Register the Blueprint

Update me-api/me-api/app.py, so that we can register the blueprint according to the config file, sorted by alphabetical: middlewares = { ... 'instagram': 'me_api.middlewares.instagram:instagram_api', ... }

3. Update the Generate Script

Update the TEMPLATE in me-api/generate.py so that we can generate its configuration, middlewares are sorted by alphabetical: "instagram": { "path": "Input the path(e.g. /photos): ", "data": { "client_id": "Input the 'Client ID' for instagram: ", "client_secret": "Input the 'Client Secret' for instagram: ", "access_token": "" } } path: where you host your middleware, for example, you can host instagram middleware on /photos. data: contain data we need when authorize our app, data should have a flat structure, don’t add another dict in data, see issue#6. Note that we need the access token, just leave it blank as showing above.

2.2.2 Build a specific middleware

This is for some specific usages, for example, develop a custom middleware only for your own sites, cause they don’t born with API support, you have to roll your own API. I’ll take my blog as an example to show you how to develop a specific middleware.

1. Add the New Middleware

In fact, it’s not difficult at all, just parse your blog posts and make an dict then return it. The result is under your control, make the modify as you like. A thousand people may have one thousand different kinds of blogs. I can’t cover them all, but I hope you can get some inspirations from this example. Remember, it’s your site, it’s your own API, feel free to build something. Here is the custom middleware for my blog: blog.py: #!/usr/bin/env python #-*- coding: utf-8 -*- from __future__ import absolute_import

2.2. Develop a new middleware 9 me-api Documentation, Release v0.1.0

import requests from flask import Blueprint, jsonify from lxml import html from me_api.cache import cache from me_api.middleware.utils import MiddlewareConfig config= MiddlewareConfig('blog') blog_api= Blueprint('blog', __name__, url_prefix=config.path)

@blog_api.route('/') @cache.cached(timeout=60*60) def index(): try: response= requests.get('http://blog.lord63.com') tree= html.fromstring(response.text) titles= [title.strip() for title in tree.xpath('//ul[@class="posts"]/li/h2/a/text()') if title.strip()] dates= tree.xpath('//small[@class="datetime muted"]/span/text()') blog={"name":"lord63's blog","powered_by":"pelican", "author":"lord63","theme":"pelican-scribble-hex", "site":"http://blog.lord63.com"} blog["posts"]=[{"title": title,"date": date} for title, date in zip(titles, dates)] except requests.RequestException as error: return jsonify(error_message=str(error.message)) if response.status_code == 200: return jsonify(blog=blog) else: return jsonify(status_code=response.status_code)

2. Register the Blueprint

Update me-api/me-api/app.py, so that we can register the blueprint according to the config file, sorted by alphabetical: middlewares = { ... 'blog': 'me_api.middlewares.blog:blog_api', ... }

3. Update the Generate Script

You can skip it, because this middleware is used only by youself. Update the TEMPLATE in me-api/generate.py, middlewares are sorted by alphabetical: "blog": { "path": "Input the path(e.g. /blog): " }

10 Chapter 2. Developer’s Guide CHAPTER 3

Additional Notes

3.1 Authors

Me-api is written and maintained by lord63 and various contributors. Please note that it’s a python port of the original Node.js version me-api, get many inspirations from it, all the glories should belong to danfang (author of original me-api) :)

3.1.1 Contributors

People who send patches and suggestions, sorted in chronological order:

3.1.2 License

Me-api is licensed under MIT license. The MIT License (MIT) Copyright (c) 2015 lord63 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documen- tation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR- TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

11