============
Introduction
============

Purpose
-------

The Opendi API is a general purpose API used by 3rd party vendors to manage
listings.

Technical description
---------------------

The API is a REST-like implementation sending JSON via HTTP. It supports a basic
authentication via an API-Key in the HTTP header. The API is accessed through
SSL. For details, see the section "Authentication".

Support for different countries
-------------------------------

The API supports multiple databases by changing the endpoint. In example, an
listing URL might contain the code “de” for naming yellow pages in Germany.
Please note, the database short code might not necessary match country codes.
The API examples use “de” as database short code, but it can be changed to other
supported codes.

Terms
-----

Customer
    A person or company, who/which has address data to offer.

Listing
    A yellow pages listing which contains business information such as name,
    address, working hours, links, etc.

Basic Listing
    A listing which contains only the basic information. See Listing model for
    the exact definition.

Enhanced Listing
    A listing which contains more extensive information. See Listing model for
    the exact definition.

Provider
    A company which sends data to Opendi on behalf of their customers. For
    example, companies who offer to distribute business addresses to multiple
    yellow pages.

Opendi ID
    An ID which is used to uniquely identify a listing. Opendi IDs are unique
    within a single country (database).

Use Cases
---------

Categories
~~~~~~~~~~

It's required to search and identify categories. It’s not allowed to create new
categories, update or delete categories.

Listings
~~~~~~~~

It's required to read, add, update, claim and suppress listings.

**Suppressed listings** are listings which are removed from the frontend and
from all searches. Listings can never be deleted from the database, thus they
are called suppressed.

**Claimed listings** are listings which are claimed by a provider. A claimed
listing can only be edited by the provider who claimed them.

Listings can be searched by telephone number. Listings can be retrieved by
Opendi ID.

Workflow description
~~~~~~~~~~~~~~~~~~~~

Provider searches for a phone number. If a listing exists, listing details are
returned with an Opendi ID. If not, zero results are returned.

The provider can create a new listing by sending a call to the “order” service.
Either an Opendi ID is returned for further reference or an error message is
shown which explains the reasons why this listing can’t be ordered. A newly
created listing is claimed automatically (the provider owns the record, the
record can’t be changed by others).

The provider can claim an existing listing by sending a call to the “claim”
service. Claiming a listing means the provider becomes the “customer”, who
actually owns this record. A provider can’t claim a listing which is claimed by
anybody else than Opendi.

If the provider finds duplicate records during its search, they can suppress
records. Records can’t be suppressed if they are owned by another provider.

Providers who are not sure about the listing category can perform a category
search in advance to find the appropriate ones.

Future versions
~~~~~~~~~~~~~~~

In future versions, listings can be claimed even when not owned by Opendi. In
this case, the actual customer is being notified and has to take action to
switch the provider.

This is most likely to be done by sending a PIN either as SMS, e-mail or by
postal address. However, the exact is yet to be defined.

The list of hosts allowed to access the API might be reduced to a certain set of
IP numbers.

Media data will be allowed to upload (Logos, Photos), instead of just links