=======
Domains
=======

    # The test framework starts out with an example domain, so let's delete
    # that first.
    >>> from mailman.interfaces.domain import IDomainManager
    >>> manager = IDomainManager(config)
    >>> manager.remove('example.com')
    <Domain example.com...>
    >>> transaction.commit()

The REST API can be queried for the set of known domains, of which there are
initially none.

    >>> dump_json('http://localhost:8001/3.0/domains')
    resource_type_link: http://localhost:8001/3.0/#domains
    start: None
    total_size: 0

Once a domain is added though, it is accessible through the API.

    >>> manager.add('example.com', 'An example domain',
    ...             'http://lists.example.com')
    <Domain example.com, An example domain,
            base_url: http://lists.example.com,
            contact_address: postmaster@example.com>
    >>> transaction.commit()

    >>> dump_json('http://localhost:8001/3.0/domains')
    entry 0:
        base_url: http://lists.example.com
        contact_address: postmaster@example.com
        description: An example domain
        email_host: example.com
        http_etag: "..."
        resource_type_link: http://localhost:8001/3.0/#domain
        self_link: http://localhost:8001/3.0/domains/example.com
        url_host: lists.example.com
    resource_type_link: http://localhost:8001/3.0/#domains
    start: 0
    total_size: 1

At the top level, all domains are returned as separate entries.

    >>> manager.add('example.org',
    ...             base_url='http://mail.example.org',
    ...             contact_address='listmaster@example.org')
    <Domain example.org, base_url: http://mail.example.org,
            contact_address: listmaster@example.org>
    >>> manager.add('lists.example.net',
    ...             'Porkmasters',
    ...             'http://example.net',
    ...             'porkmaster@example.net')
    <Domain lists.example.net, Porkmasters,
            base_url: http://example.net,
            contact_address: porkmaster@example.net>
    >>> transaction.commit()

    >>> dump_json('http://localhost:8001/3.0/domains')
    entry 0:
        base_url: http://lists.example.com
        contact_address: postmaster@example.com
        description: An example domain
        email_host: example.com
        http_etag: "..."
        resource_type_link: http://localhost:8001/3.0/#domain
        self_link: http://localhost:8001/3.0/domains/example.com
        url_host: lists.example.com
    entry 1:
        base_url: http://mail.example.org
        contact_address: listmaster@example.org
        description: None
        email_host: example.org
        http_etag: "..."
        resource_type_link: http://localhost:8001/3.0/#domain
        self_link: http://localhost:8001/3.0/domains/example.org
        url_host: mail.example.org
    entry 2:
        base_url: http://example.net
        contact_address: porkmaster@example.net
        description: Porkmasters
        email_host: lists.example.net
        http_etag: "..."
        resource_type_link: http://localhost:8001/3.0/#domain
        self_link: http://localhost:8001/3.0/domains/lists.example.net
        url_host: example.net
    resource_type_link: http://localhost:8001/3.0/#domains
    start: 0
    total_size: 3


Individual domains
==================

The information for a single domain is available by following one of the
self_links from the above collection.

    >>> dump_json('http://localhost:8001/3.0/domains/lists.example.net')
    base_url: http://example.net
    contact_address: porkmaster@example.net
    description: Porkmasters
    email_host: lists.example.net
    http_etag: "..."
    resource_type_link: http://localhost:8001/3.0/#domain
    self_link: http://localhost:8001/3.0/domains/lists.example.net
    url_host: example.net

But we get a 404 for a non-existent domain.

    >>> dump_json('http://localhost:8001/3.0/domains/does-not-exist')
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 404: Not Found


Creating new domains
====================

New domains can be created by posting to the 'domains' url.  However
lazr.restful requires us to use a 'named operation' instead of posting
directly to the URL.

    >>> dump_json('http://localhost:8001/3.0/domains', {
    ...           'ws.op': 'new',
    ...           'email_host': 'lists.example.com',
    ...           })
    URL: http://localhost:8001/3.0/domains
    content-length: 0
    content-type: text/plain;charset=utf-8
    date: ...
    location: http://localhost:8001/3.0/domains/lists.example.com
    server: WSGIServer/... Python/...
    x-content-type-warning: guessed from content
    x-powered-by: Zope (www.zope.org), Python (www.python.org)

Now the web service knows about our new domain.

    >>> dump_json('http://localhost:8001/3.0/domains/lists.example.com')
    base_url: http://lists.example.com
    contact_address: postmaster@lists.example.com
    description: None
    email_host: lists.example.com
    http_etag: "..."
    resource_type_link: http://localhost:8001/3.0/#domain
    self_link: http://localhost:8001/3.0/domains/lists.example.com
    url_host: lists.example.com

And the new domain is in our database.

    >>> manager['lists.example.com']
    <Domain lists.example.com,
            base_url: http://lists.example.com,
            contact_address: postmaster@lists.example.com>

    # Unlock the database.
    >>> transaction.abort()

You can also create a new domain with a description, a base url, and a contact
address.

    >>> dump_json('http://localhost:8001/3.0/domains', {
    ...           'ws.op': 'new',
    ...           'email_host': 'my.example.com',
    ...           'description': 'My new domain',
    ...           'base_url': 'http://allmy.example.com',
    ...           'contact_address': 'helpme@example.com'
    ...           })
    URL: http://localhost:8001/3.0/domains
    content-length: 0
    content-type: text/plain;charset=utf-8
    date: ...
    location: http://localhost:8001/3.0/domains/my.example.com
    server: WSGIServer/... Python/...
    x-content-type-warning: guessed from content
    x-powered-by: Zope (www.zope.org), Python (www.python.org)

    >>> dump_json('http://localhost:8001/3.0/domains/my.example.com')
    base_url: http://allmy.example.com
    contact_address: helpme@example.com
    description: My new domain
    email_host: my.example.com
    http_etag: "..."
    resource_type_link: http://localhost:8001/3.0/#domain
    self_link: http://localhost:8001/3.0/domains/my.example.com
    url_host: allmy.example.com

    >>> manager['my.example.com']
    <Domain my.example.com, My new domain,
            base_url: http://allmy.example.com,
            contact_address: helpme@example.com>

    # Unlock the database.
    >>> transaction.abort()