Improve API documentation

[cutoffthetop]

• document data schema for each endpoint
• give examples for common use cases
• describe parameters and their possible values
• explain query syntax
• frequently asked questions
• more comprehensive terms of use

[ctriroli]

Es sollte auch eine Lizenz-Dokumentation (Was darf ich, was darf ich nicht?) - also nicht lediglich eine technische - geben. Die allgemeinen Nutzungsbedingungen von Zeit Online sind IMO in einigen Punkten nicht spezifisch genug.

[spier]

Some specific cases of missing documentation (as of 2012/11/25) are:

• the /content endpoint misses documentation for sort and fq
• the /product/{id} endpoint misses documentation for the search parameters
• some endpoints that allow searches are missing the operator parameter (although it is probably allowed)
• the /series/{id} endpoint does not work at all. Error: "Due to an internal error the request could not be fulfilled."
• the documentation states possible keyword types as: location, person, organisation or issue. When searching for keywords I also see subject though.
• the documentation of the search query syntax (parameter q) is not sufficient. It looks like under the hood Lucene is being used but that is just a guess.
• potentially the calls /author/{id}, /department/{id}, /keyword/{id}, /product/{id}, and /series/{id} should all be grouped below the content endpoint, as all of them are returning articles. The documentation is confusing as it e.g. states "Get keyword by ID", although the API call returns articles and not keywords.
• documentation of the id parameter is missing. This parameter is part of the path, and not part of the query but nevertheless it is a parameter.
• what are the maximum values for limit and offset?

[cutoffthetop]

We have added a new general page to the documentation http://developer.zeit.de/docs wich addresses some of the issues mentioned here. But we will keep working on the docs.