Welcome to the guide for InterFAX library contributors. This document will help you get set up and started on library development, and helps to outline the required output we're looking to achieve.
InterFAX provides a simple REST API for sending and receiving faxes. Faxes can be sent in the following ways:
- By uploading a document (PDF, Word Doc, etc) to InterFAX and then pointing to the URI for that document when sending a fax
- By providing the binary data of the document in the body of a POST request
- By providing a URL of a HTML page to be fetched and faxed
Receiving a fax is mostly done asynchronously of this library. The API provides some methods to query new documents, mark them as read, and download the images for further processing.
The goal is to make a set of new libraries in various languages that:
- Wrap (most) of the InterFAX REST API
- Allow for sending of a fax in as few lines as is reasonable
- Wrap the erroneous and fragile process of reading binary dating and posting this to the server
- Provide a simple DSL to make the API truly enjoyable to work with
To be able to send a fax you will need a Developer Account with an approved inbound fax number. Please do not set one up yourself. We will provide you with one.
To prevent abuse every developer account is limited to a single "approved fax number". What this means is that you will only be able to send faxes to this number, which will also function as your own inbound number.
In other words: you can only send faxes to yourself. Sending faxes to anyone else will result in API errors. Please make sure to use your approved inbound number for testing.
Your developer account will be set up with some credits to allow you to send and receive faxes. If you run out please contact Adam.
Please use this test fax in your tests.
We currently have two libraries implemented: .NET and Ruby. Please use these as references when needed.
We are looking to cover most APIs available on the InterFAX REST API. This includes all options and variations. In other words we want to cover:
-
Sending faxes
- Send fax
- Get fax list
- Get completed fax list
- Get fax record
- Get fax image
- Cancel fax
- Search fax list
- Resend fax
- Hide fax
- Uploading documents (and every sub-call involved)
- Get outbound credits
-
Receiving faxes
- Get list
- Get record
- Get image
- Get forwarding emails
- Mark
- Resend
The only exceptions are every API call concerning "Sending batches" (/outbound/batches).
We leave with the freedom to decided to build a custom DSL (domain specific language) for the InterFAX library or not. For example, the Ruby library provides direct shortcuts to cancelling a fax from the fax object.
Please keep in mind the "Goals" above and the best practices in your language to fill in your preferred way of building this library.
Where possible if the API returns a non-200 response this error should be passed to the user. (aka it should not be caught)
Ideally your library should follow some of the principles outlined in the 12-factor principle.
- Clients should be instantiable with credentials directly, OR by the use of environment variable.
- Multiple clients should be instantiable and should be able to exist at the same time
- When instantiating a client, explicitly provided credentials should override environment variables.
For the environment variables please use: INTERFAX_USERNAME and INTERFAX_PASSWORD.
- Library: ideally we'd use
interfax,interfax/interfaxorInterFAX, whichever is more idiomatic to the language. - Class names: ideally we'd use
InterFAXbut if this is an issue thanInterfaxwill do - Lower case: ideally we'd use
interfax, notinter_fax
The following files are required:
- This LICENSE
- A
README.mdwith documentation - A
.gitignoreto exclude unwanted build files - This CONTRIBUTING.md
- A
travis.ymlfor all relevant language versions to test the library against
Additionally please split your source code into source, test and build folders when needed.
Please use the MIT license atached and reference to this from the documentation and from the source code or packaging files (where applicable).
Please refer to InterFAX <[email protected]> as the primary contributor/owner for the library (where applicable). You can refer to yourself and your email address as a secondary contributor (where possible). See the Ruby gem for an example.
The source code should be published to github at the following location.
https://github.com/interfax/interfax-{language}
Please keep build/distribution files out of Github where possible.
We'd like your help to publish the libraries to their respective most popular package managers. This would be:
- Java (?) - http://mvnrepository.com
- .Net - https://nuget.org
- PHP - https://packagist.org
- Ruby - https://rubygems.org
- Python - https://pypi.python.org/pypi
- Node.js - https://www.npmjs.com
Any feedback on these choices is more than welcome.
When releasing a new version please:
- Tag the release in github.
- Add release notes to the
CHANGELOG.mdand/or theRELEASEStab on Github - Apply semver rules
Documentation is as important for a useful library as the code itself. We have identified the following core requirements for every library.
Please add a clear short title, e.g. "InterFAX {language} library". Additionally please add a badge for the version of your published library and the Travis badge for the build status. For example:
Please use a short description to highlight the following things:
- The language this library is for
- That it uses the REST API
- That it uses HTTPS
- That this library lets you "send and receive faxes"
Please highlight language requirements, like the version of the language supported and any other things to consider
Please add clear instruction on how to install the library from the package manager. If it is common to install the library without the package manager then also provide instructions for this.
Provide with a simple 3-5 line example on how to initialise the library and send your first fax.
After the installation and getting started docs please document every public API method of your library as follows:
- A title of the call
- The method signature
- A short description of the call (you can copy this from the Ruby library)
- A link to the relevant REST reference documentation
- A list of accepted arguments/options/parameters for the method
- A short code sample showing the method being used and a sample response
Please do not document the arguments and response in detail. Instead point to the relevant pages in the REST reference documentation.
Please write a short but simple paragraph/list on how to contribute to this project.
A link to the LICENSE is required in the documentation.
Your code should be well tested. Please apply the following guidelines:
- Test your library, not the API
- Do not make any actual API calls in your tests
- Use a NET/HTTP mocking framework if needed
- Do not actually write to disk when testing saving files
- Use a filesystem mocking framework if needed
Additionally prove a .travis.yml for your language. We will set your project up on Travis for testing. Please cover the following:
- Every common language version still
- In Use
- Officially supported
- Additionally if possible set add your language's latest build (e.g.
ruby-head) but set this one to allow to fail.
For example:
language: ruby
sudo: false
cache: bundler
rvm:
- 2.1
- 2.2
- 2.3.1
- ruby-head
matrix:
allow_failures:
- rvm: ruby-headIn some languages you can spin up a interactive shell, import the library, and start playing around with it. In others you can't; you either need to set up an entire project first (iOS) or you need to integrate it deeper into a framework (.NET). For these please provide the following 3 samples besides the documentation specified earlier.
These samples should live in a separate project. Ideally this should be named:
https://github.com/interfax/interfax-{language}-samples
Showcase how to send a fax from a document in a file.
Additionally show:
- How to get the Fax ID for the fax sent
- How to get the current status of the fax
- How to get the image for the fax sent and save it to disk
Showcase how to use get a list of sent faxes.
Additionally show:
- How to filter the list
- How to inspect the status of one of the faxes in the list
Showcase how to use get a list of received faxes.
Additionally show:
- How to mark a fax as read
- How to get the image for the fax received and save it to disk