Me-Api Documentation Release V0.1.0
Total Page:16
File Type:pdf, Size:1020Kb
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.