OSD & DPS909 Winter 2018 Release 0.1
Contents
0.1 Release
Introduction
You are asked to create an open source RESTful API web service that can find and extract phone numbers from submitted resources, and be used in a microservice architecture. See below for details about how the API should function.
Your first release will be due in multiple stages:
- Part A: Create an initial, partial implementation, due Feb 1 by midnight
- Part B: Contribute to another student's implementation, due Feb 19 by midnight
The goal of this first release is to practice, and make sure you are comfortable with common open source workflows, including:
- using git and GitHub
- managing GitHub repositories
- creating common project and build artifacts in an open source repo (e.g., LICENSE, Readme.md, automation, etc)
- working with third-party dependencies
- creating and responding to Issues
- creating Pull Requests
- reviewing and merging Pull Requests
- the differences between being a maintainer and a contributor in an open source project
API Description
Phone numbers seem like a simple thing to work with at first, but it gets complicated quickly. Thankfully, the problem of working with phone numbers anywhere on Earth has already been solved by Google, and the code made open source:
https://github.com/googlei18n/libphonenumber
You are asked to use libphonenumber to create a web service, using whatever programming language you want. Your web server must support the following API endpoints, which all return JSON formatted responses:
1. GET /api/phonenumbers/parse/text/{...string...} to allow sending small snippets of text to be parsed.
For example, requesting /api/phonenumbers/parse/text/nothing should return an empty list []. Whereas requesting requesting /api/phonenumbers/parse/text/Seneca%20Phone%20Number%3A%20416-491-5050 should return a list with a single, formatted phone number ["(416) 491-5050"].
2. POST /api/phonenumbers/parse/file with the request's Content-Type being text/plain and the body containing a base64 encoded text file. This allows larger files to be processed, in addition to small bits of text.
All responses from the API should be given in JSON format, with the exception of errors, which can use HTTP status codes (e.g., 4xx codes).
Phone numbers returned from any of the endpoints above should not be duplicated. That is, if a given input includes a phone number more than once, you should only return one copy of it.
Part A Requirements
Create a new GitHub repo for your web service. Pick an open source license for your code, making sure it is compatible with libphonenumber and any other dependencies you use. Make sure your repo has both a LICENSE and README.md file, and that your README.md has clear instructions on how to use your code.
Using any programming language you like, write a server that implements the API described above. You must also include tests to prove that your server implements the API correctly. These tests need to be runnable from the command-line. You may use any testing framework, and test runner you like.
File some Issues in your repo for enhancements that you'd like to see done to your server. Here are some suggestions, but feel free to file anything you like for fixes/enhancements you need:
- Write more tests to deal with various edge cases
- Add support for parsing a resource at a given URL:
GET /api/phonenumbers/url/http%3A%2F%2Fexample.com%2Fwould cause the server to load the content at http://example.com and parse it for phone numbers. - Add support for parsing MS Word docs. There are lots of existing open source projects that can help parse a Word doc into Text, which can then be parsed by your earlier code
- Add support for parsing PDF files. There are lots of existing open source projects that can help parse a PDF into Text, which can then be parsed by your earlier code
- Add support for parsing images. Use an OCR (e.g., https://github.com/tesseract-ocr/tesseract or http://tesseract.projectnaptha.com/) tool to first extract text from the image, then parse it as you did earlier
- Add automatic linting to the code, using something like eslint. Linters find bugs and style issues.
- Add an example client (e.g., web page) that can be used to manually test the API with various types of inputs
- Add support for running the server on a cloud service like Heroku
- Add automatic continuous integration (CI) via TravisCI, CircleCI, etc.
Make sure your repo has all your code and tests completed before moving to Part B.
Part B Requirements
Find another student's repo and pick two Issues you'd like to work on, or file your own to fix things you notice are broken. Leave a comment in the issues to let others know that you're working on this (NOTE: only 1 student can work on an issue at a time).
Fork this other student's repo, and create a clone of it. Make a branch for each of the issues you want to fix. For example, if you are fixing Issue 12, create a new branch named issue12: git checkout -b issue12 master. Now fix the code and create a Pull Request to get your changes added.
4. Submission
All submissions are done electronically via GitHub and your blog. Please add info to the table below when you are done one of the sections.
Part A: after you have created your repo, added your code and tests, and filed some issues, add your repo URL.
Part B: include URLs to two PRs you made to other student's repos.
Blog Post: after Part A and B are done, do your blog post. Your final blog post should discuss the following:
- What did you build? Discuss your web service (e.g., what is its name, how does it work, etc.) and include links so people can find it.
- What was your process for doing this assignment?
- Which language, dependencies, and tools did you use? Why did you choose them?
- What did you find challenging about your work?
- Compare the experience of being a maintainer to that of contributing to someone else's project. Which did you enjoy more? Why?
- What did you learn as you did this work?
- What do you still want to learn more about in subsequent releases?
