tantona/cleardata repository overview

⁠ClearDATA Assessment

⁠Challenge

Provide an HTTP API that takes a string input and returns if that string is a pangram. (Use the language and methods you feel best, but be prepared to defend them).

⁠Prerequisites

In order to run the following API on your machine you must have the following installed and configured on your machine.

1. docker
2. curl
3. optional
   • newman⁠
   • jq⁠ - if you want pretty output on the command line
   • postman⁠

⁠Pangram Definition

A sentence which uses every letter of a given alphabet at least once.

Examples⁠

⁠Constraints on input

1. Input is in English
2. Will return an error if the input contains multiple sentences. (preceding punctuation is stripped)
3. Accented characters count as their base character (ie. á -> a) https://blog.golang.org/normalization⁠
4. Characters like ß and œ are not normalized.

⁠Getting started

1. Run Tests

   make test
   

   Copy

2. Run API

   docker-compose up
   

   Copy

3. Run integration tests

   make integration
   

   Copy

4. Make a call against the pangram endpoint

   # Successful
   curl -i -XPOST -d '{"text": "The quick brown fox jumps over the lazy dog!"}' http://localhost:8080/tests/pangram
   
   # Unsuccessful
   curl -i -XPOST -d '{"text": "is this a pangram?"}' http://localhost:8080/tests/pangram
   
   # Error
   curl -i -XPOST -d '{"text": "is this a pangram? What about this one?"}' http://localhost:8080/tests/pangram
   

   Copy

There's also a postman collection you can import and use to make these calls if you don't like curl 😃

⁠TODO:

1. Version the API

2. Add logging!

3. Add Metrics

4. Other endpoints to test various things (i.e. palindromes, anagrams, prime numbers)

5. Other languages OR Define your own alphabet (with customizable normalization)

6. Character count

7. Add other methods (ie. GET Generates a pangram and returns it)

8. If customer requirments dictate - evaluate using a language processing library (or writing one) for more complex normalization/transformation

9. Use multistage docker build for smaller docker image

10. Use an assertion library (if it's becomes necessary)

11. Add clean shutdown

⁠Notes

1. I feel that I should mention that I was not going for a REST-ful API here. This also does not follow any JSON-RPC specification either. It is a custom "rpc style" HTTP API. If I were to flesh this out into a service I would want to follow some conventions to offload the cognitive burden of "inventing" our own architecture and expectations around requests and responses.

2. To avoid yagni - I refrained from making too many "well it would be cool if we could to this" while leaving the service extensible with some minor refactoring.

3. I included more comments than I would normally in the code to assist quick readability. I believe the code should be clear and easy to reason about (tests help).

4. I was having fun with some automation so I added things like automated dockerhub builds, circleci w/ status badge, and newman integration tests via postman cli.

5. Turns out there are a ton of edge cases and language processing is hard. I'd be interested in looking into some "C"lever ways of handling/normalizing input for different languages/keyboars/character sets etc. Seems like there are probably libraries out there that handle these kinds of things more elegantly than my quickly thrown together helpers 😃

6. I thought this was a nice little project for a coding excercise. The requirements provided were just enough for me to implement this in a number of different ways and I think It provides a great platform for discussion. In the real world centralizing such a simple service like this might be a little strange as IsPangram could exist in a library that our client consumes - For example, it would be reasonable to offload this work to a browser.