{"id":23613715,"url":"https://github.com/interfax/contributor-instructions","last_synced_at":"2026-01-26T01:02:18.928Z","repository":{"id":94734582,"uuid":"63406763","full_name":"interfax/contributor-instructions","owner":"interfax","description":null,"archived":false,"fork":false,"pushed_at":"2016-09-12T14:28:32.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-12-02T02:35:42.830Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interfax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-15T08:50:36.000Z","updated_at":"2016-08-09T10:43:06.000Z","dependencies_parsed_at":"2023-05-17T21:45:46.379Z","dependency_job_id":null,"html_url":"https://github.com/interfax/contributor-instructions","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/interfax/contributor-instructions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Fcontributor-instructions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Fcontributor-instructions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Fcontributor-instructions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Fcontributor-instructions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interfax","download_url":"https://codeload.github.com/interfax/contributor-instructions/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Fcontributor-instructions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28763093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T00:37:26.264Z","status":"ssl_error","status_checked_at":"2026-01-26T00:37:25.959Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-27T17:19:16.548Z","updated_at":"2026-01-26T01:02:18.914Z","avatar_url":"https://github.com/interfax.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Library contributors guide\n\nWelcome 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.\n\n- [Introduction to InterFAX](#introduction-to-interfax)\n\t- [Goals](#goals)\n- [Getting a Developer Account](#getting-a-developer-account)\n\t- [Approved inbound number](#approved-inbound-number)\n\t- [Credits](#credits)\n\t- [Test fax](#test-fax)\n- [Deliverables](#deliverables)\n\t- [Library](#library)\n\t\t- [Example libraries](#example-libraries)\n\t\t- [API Coverage](#api-coverage)\n\t\t- [DSL](#dsl)\n\t\t- [Errors](#errors)\n\t\t- [Conventions](#conventions)\n\t\t- [Licensing](#licensing)\n\t- [Publishing](#publishing)\n\t\t- [Ownership](#ownership)\n\t\t\t- [Source](#source)\n\t\t\t- [Distribution](#distribution)\n\t\t\t- [Releases](#releases)\n\t- [Documentation](#documentation)\n\t\t- [Title and badges](#title-and-badges)\n\t\t- [Installation](#installation)\n\t\t- [Getting started](#getting-started)\n\t\t- [Reference](#reference)\n\t\t- [Contribution](#contribution)\n\t\t- [License](#license)\n\t- [Tests](#tests)\n\t\t- [Scope](#scope)\n\t\t- [Travis](#travis)\n\t- [Samples](#samples)\n\n\n## Introduction to InterFAX\n\nInterFAX provides a simple REST API for sending and receiving faxes. Faxes can be sent in the following ways:\n\n\n* By uploading a document (PDF, Word Doc, etc) to InterFAX and then pointing to the URI for that document when sending a fax\n* By providing the binary data of the document in the body of a POST request\n* By providing a URL of a HTML page to be fetched and faxed\n\nReceiving 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.\n\n### Goals\n\nThe goal is to make a set of new libraries in various languages that:\n\n- Wrap (most) of the InterFAX REST API\n- Allow for sending of a fax in as few lines as is reasonable\n- Wrap the erroneous and fragile process of reading binary dating and posting this to the server\n- Provide a simple DSL to make the API truly enjoyable to work with\n\n---\n\n## Getting a Developer Account\n\nTo 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.\n\n### Approved inbound number\n\nTo 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.\n\nIn 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.\n\n### Credits\n\nYour developer account will be set up with some credits to allow you to send and receive faxes. If you run out please contact [Adam](mailto:adam@interfax.net).\n\n### Test fax\n\nPlease use [this test fax](test.pdf) in your tests.\n\n---\n\n\n## Deliverables\n\n### Library\n\n#### Example libraries\n\nWe currently have two libraries implemented: [.NET](https://github.com/interfax/interfax-dotnet) and [Ruby](https://github.com/interfax/interfax-ruby). Please use these as references when needed.\n\n#### API Coverage\n\nWe are looking to cover most APIs available on the [InterFAX REST API](https://www.interfax.net/en/dev/rest/reference). This includes all options and variations. In other words we want to cover:\n\n- Sending faxes\n\n  - Send fax\n  - Get fax list\n  - Get completed fax list\n  - Get fax record\n  - Get fax image\n  - Cancel fax\n  - Search fax list\n  - Resend fax\n  - Hide fax\n  - Uploading documents (and every sub-call involved)\n  - Get outbound credits\n\n- Receiving faxes\n\n  - Get list\n  - Get record\n  - Get image\n  - Get forwarding emails\n  - Mark\n  - Resend\n\nThe only exceptions are **every** API call concerning \"Sending batches\" (`/outbound/batches`).\n\n#### DSL\n\nWe 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.\n\nPlease keep in mind the \"Goals\" above and the best practices in your language to fill in your preferred way of building this library.\n\n#### Errors\n\nWhere possible if the API returns a non-200 response this error should be passed to the user. (aka it should not be caught)\n\n#### Conventions\n\n##### Client initialization\n\nIdeally your library should follow some of the principles outlined in the  [12-factor](http://12factor.net/config) principle.\n\n* Clients should be instantiable with credentials directly, **OR** by the use of environment variable.\n* Multiple clients should be instantiable and should be able to exist at the same time\n* When instantiating a client, explicitly provided credentials should override environment variables.\n\nFor the environment variables please use: `INTERFAX_USERNAME` and `INTERFAX_PASSWORD`.\n\n##### Naming\n\n* **Library:** ideally we'd use `interfax`, `interfax/interfax` or `InterFAX`, whichever is more idiomatic to the language.\n* **Class names:** ideally we'd use `InterFAX` but if this is an issue than `Interfax` will do\n* **Lower case:** ideally we'd use `interfax`, not `inter_fax`\n\n##### Files\n\nThe following files are required:\n\n- This [LICENSE](LICENSE)\n- A `README.md` with documentation\n- A `.gitignore` to exclude unwanted build files\n- This [CONTRIBUTING.md](CONTRIBUTING.md)\n- A `travis.yml` for all relevant language versions to test the library against\n\nAdditionally please split your source code into source, test and build folders when needed.\n\n#### Licensing\n\nPlease use the [MIT license atached](LICENSE) and reference to this from the documentation and from the source code or packaging files (where applicable).\n\n---\n\n### Publishing\n\n#### Ownership\n\nPlease refer to `InterFAX \u003cdev@interfax.net\u003e` 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.\n\n##### Source\n\nThe source code should be published to github at the following location.\n\n`https://github.com/interfax/interfax-{language}`\n\nPlease keep build/distribution files out of Github where possible.\n\n##### Distribution\n\nWe'd like your help to publish the libraries to their respective most popular package managers. This would be:\n\n- Java (?) - \u003chttp://mvnrepository.com\u003e\n- .Net - \u003chttps://nuget.org\u003e\n- PHP - \u003chttps://packagist.org\u003e\n- Ruby - \u003chttps://rubygems.org\u003e\n- Python - \u003chttps://pypi.python.org/pypi\u003e\n- Node.js - \u003chttps://www.npmjs.com\u003e\n\nAny feedback on these choices is more than welcome.\n\n##### Releases\n\nWhen releasing a new version please:\n\n- Tag the release in github.\n- Add release notes to the `CHANGELOG.md` and/or the `RELEASES` tab on Github\n- Apply [semver rules](http://semver.org/)\n\n---\n\n### Documentation\n\nDocumentation is as important for a useful library as the code itself. We have identified the following core requirements for every library.\n\n#### Title and badges\n\nPlease 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:\n\n[![Gem Version](https://badge.fury.io/rb/interfax.svg)](https://badge.fury.io/rb/interfax) [![Build Status](https://travis-ci.org/interfax/interfax-ruby.svg?branch=master)](https://travis-ci.org/interfax/interfax-ruby)\n\n#### Description\n\nPlease use a short description to highlight the following things:\n\n* The language this library is for\n* That it uses the REST API\n* That it uses HTTPS\n* That this library lets you \"send and receive faxes\"\n\n#### Requirements\n\nPlease highlight language requirements, like the version of the language supported and any other things to consider\n\n#### Installation\n\nPlease 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.\n\n#### Getting started\n\nProvide with a simple 3-5 line example on how to initialise the library and send your first fax.\n\n#### Reference\n\nAfter the installation and getting started docs please document every public API method of your library as follows:\n\n* A title of the call\n* The method signature\n* A short description of the call (you can copy this from the Ruby library)\n* A link to the relevant REST reference documentation\n* A list of accepted arguments/options/parameters for the method\n* A short code sample showing the method being used and a sample response\n\nPlease do not document the arguments and response in detail. Instead point to the relevant pages in the [REST reference documentation](https://www.interfax.net/en/dev/rest/reference).\n\n#### Contribution\n\nPlease write a short but simple paragraph/list on how to contribute to this project.\n\n#### License\n\nA link to the [LICENSE](LICENSE) is required in the documentation.\n\n---\n\n### Tests\n\nYour code should be well tested. Please apply the following guidelines:\n\n* Test your library, not the API\n* Do not make any actual API calls in your tests\n  * Use a NET/HTTP mocking framework if needed\n* Do not actually write to disk when testing saving files\n  * Use a filesystem mocking framework if needed\n\n#### Travis\n\nAdditionally prove a `.travis.yml` for your language. We will set your project up on Travis for testing. Please cover the following:\n\n* Every common language version still\n  1. In Use\n  2. Officially supported\n* Additionally if possible set add your language's latest build (e.g. `ruby-head`) but set this one to allow to fail.\n\nFor example:\n\n```yml\nlanguage: ruby\nsudo: false\ncache: bundler\nrvm:\n  - 2.1\n  - 2.2\n  - 2.3.1\n  - ruby-head\nmatrix:\n  allow_failures:\n    - rvm: ruby-head\n```\n\n----\n\n### Samples\n\nIn 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.\n\nThese samples should live in a separate project. Ideally this should be named:\n\n`https://github.com/interfax/interfax-{language}-samples`\n\n#### Send a fax\n\nShowcase how to send a fax from a document in a file.\n\nAdditionally show:\n\n* How to get the Fax ID for the fax sent\n* How to get the current status of the fax\n* How to get the image for the fax sent and save it to disk\n\n#### Get fax list\n\nShowcase how to use get a list of sent faxes.\n\nAdditionally show:\n\n* How to filter the list\n* How to inspect the status of one of the faxes in the list\n\n#### Receive a fax\n\nShowcase how to use get a list of received faxes.\n\nAdditionally show:\n\n* How to mark a fax as read\n* How to get the image for the fax received and save it to disk\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Fcontributor-instructions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterfax%2Fcontributor-instructions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Fcontributor-instructions/lists"}