├── src └── zeit │ ├── api │ ├── __init__.py │ ├── templates │ │ ├── error.html │ │ ├── docs │ │ │ ├── client.html │ │ │ ├── series.html │ │ │ ├── product.html │ │ │ ├── author.html │ │ │ ├── department.html │ │ │ ├── keyword.html │ │ │ └── content.html │ │ ├── licence.html │ │ ├── index.html │ │ ├── explorer.html │ │ ├── quickstart.html │ │ ├── docs.html │ │ ├── style.css │ │ └── base.html │ ├── schemas │ │ ├── solrmsg.rnc │ │ ├── database.sql │ │ └── schema_.xml │ ├── access.py │ ├── settings.py │ ├── application.py │ ├── util.py │ ├── exception.py │ ├── metadata.py │ ├── blueprints.py │ ├── parameters.py │ ├── tests.py │ └── queries.py │ └── __init__.py ├── bootstrap.sh ├── .gitignore ├── modwsgi.cfg ├── setup.py ├── generate-key.py ├── CHANGES.md ├── dev.cfg ├── LICENCE.md └── README.md /src/zeit/api/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/zeit/__init__.py: -------------------------------------------------------------------------------- 1 | __import__('pkg_resources').declare_namespace(__name__) -------------------------------------------------------------------------------- /bootstrap.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | virtualenv --python=python2.7 . 4 | bin/pip install zc.buildout==2.12.0 5 | bin/buildout 6 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.py[cod] 2 | *.egg 3 | *.egg-info 4 | *.wsgi 5 | .Python 6 | dist 7 | build 8 | eggs 9 | etc 10 | include 11 | lib 12 | parts 13 | bin 14 | var 15 | sdist 16 | develop-eggs 17 | .installed.cfg 18 | private.py -------------------------------------------------------------------------------- /modwsgi.cfg: -------------------------------------------------------------------------------- 1 | [app:api] 2 | paste.app_factory = zeit.api.application:api_factory 3 | 4 | [app:api_dev] 5 | paste.app_factory = zeit.api.application:api_dev_factory 6 | 7 | [app:doc] 8 | paste.app_factory = zeit.api.application:doc_factory 9 | 10 | [app:doc_dev] 11 | paste.app_factory = zeit.api.application:doc_dev_factory 12 | -------------------------------------------------------------------------------- /src/zeit/api/templates/error.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Not Found{% endblock %} 3 | {% block docBody %} 4 |

The requested URL does not exist. Sorry about that.

5 |

You might want to check your spelling or navigate using the menu.

6 |

Start over.

7 | {% endblock %} -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup, find_packages 2 | 3 | name = 'zeit.api' 4 | setup( 5 | name = name, 6 | version = '0.4', 7 | author = 'Nicolas Drebenstedt', 8 | author_email = 'nicolas.drebenstedt@zeit.de', 9 | url = 'https://github.com/ZeitOnline/content-api', 10 | package_dir = {'': 'src'}, 11 | packages = find_packages('src'), 12 | namespace_packages = ['zeit',], 13 | include_package_data = True, 14 | install_requires = [ 15 | 'setuptools', 16 | 'flask', 17 | 'lxml' 18 | ], 19 | zip_safe = False, 20 | entry_points = """ 21 | [console_scripts] 22 | api = zeit.api.application:run_local_api 23 | doc = zeit.api.application:run_local_doc 24 | """, 25 | ) 26 | -------------------------------------------------------------------------------- /generate-key.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python 2 | 3 | from datetime import datetime 4 | import os 5 | import sqlite3 6 | import sys 7 | import time 8 | 9 | db = sqlite3.connect('/var/lib/zon-api/data.db') 10 | 11 | if len(sys.argv) < 3: 12 | print('Usage: %s "Firstname Lastname" email@example.com' % sys.argv[0]) 13 | print('\nLast keys:') 14 | query = 'SELECT * FROM client ORDER by reset DESC' 15 | for client in db.execute(query): 16 | reset = datetime.fromtimestamp(client[5]) 17 | print(u'{0}: "{2}" {3} ({reset})'.format(*client, reset=reset).encode('utf8')) 18 | sys.exit(1) 19 | 20 | api_key = str(os.urandom(26).encode('hex')) 21 | tier = 'free' 22 | name = sys.argv[1] 23 | email = sys.argv[2] 24 | requests = 0 25 | reset = int(time.time()) 26 | query = 'INSERT INTO client VALUES (?, ?, ?, ?, ?, ?)' 27 | db.execute(query, (api_key, tier, name, email, requests, reset)) 28 | db.commit() 29 | db.close() 30 | print api_key 31 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/client.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Client{% endblock %} 3 | {% block docBody %} 4 | 5 |

Observe your usage

6 | 7 |

8 | The user endpoint is not a content resource per se, but lets you get 9 | information about your API usage. As this is sensitive information, 10 | requests must be authorized. Parameters are not required. 11 |

12 | 13 |

Endpoint

14 |

{{ api_url }}/client

15 | 16 |

Example

17 | 18 |

Request

19 |

GET /client HTTP/1.1
20 | Host: {{ api_url }}
21 | X-Authorization: abcdefg1234xyz56789
22 |

23 | 24 |

Response

25 |

{
26 |     "reset": 1352820867,
27 |     "tier": "free",
28 |     "name": "Jane Mustermann",
29 |     "email": "jane@muster.com"
30 |     "requests": 13,
31 |     "api_key": "abcdefg1234xyz56789",
32 |     "quota": 10000
33 | }
34 |

35 | {% endblock %} -------------------------------------------------------------------------------- /CHANGES.md: -------------------------------------------------------------------------------- 1 | #Changelog 2 | 3 | ## 25. Apr 2013 4 | * [FIXED] URLs for sub-departments now working correctly 5 | 6 | ## 21. Apr 2013 7 | * [FIXED] Keyword IDs are now URL-safe 8 | 9 | ##02. Jan 2013 10 | * [IMPROVED] API explorer performance 11 | 12 | ##21. Dec 2012 13 | * [IMPROVED] General documentation expanded 14 | * [IMPROVED] Cosmetic changes at developer portal 15 | * [DEPRECATED] App Gallery removed, now only at our blog 16 | 17 | ##20. Dec 2012 18 | * [FIXED] Server errors at /content resolved 19 | * [FIXED] UTF8 support for all parameters 20 | * [IMPROVED] Performance optimizations for /author 21 | * [ADDED] Id field for non-content searches 22 | * [ADDED] Href field for authors, if available 23 | 24 | ##05. Dec 2012 25 | * [ADDED] Uuid field for content objects 26 | 27 | ##04. Dec 2012 28 | * [FIXED] Response header gets proper encoding 29 | 30 | ##30. Nov 2012 31 | * [FIXED] Related articles now have proper titles 32 | 33 | ##23. Nov 2012 34 | * [ADDED] Initial beta release -------------------------------------------------------------------------------- /src/zeit/api/schemas/solrmsg.rnc: -------------------------------------------------------------------------------- 1 | # 2 | # zeit.api.schemas.solrmsg 3 | # ~~~~~~~~~~~~~~~~~~~~~~~~ 4 | # 5 | # RelaxNG schema for messages to update articles in the Solr index. 6 | # For more info see: http://wiki.apache.org/solr/UpdateXmlMessages 7 | # 8 | # Copyright: (c) 2013 by ZEIT ONLINE. 9 | # License: BSD, see LICENSE.md for more details. 10 | # 11 | 12 | 13 | default namespace = "" 14 | 15 | start = 16 | element doc { 17 | element field { attribute name { 'related' }, text }*, 18 | element field { attribute name { 'keyword' }, text }*, 19 | element field { attribute name { 'author' }, text }+, 20 | element field { attribute name { 'product' }, text }?, 21 | element field { attribute name { 'release_date' }, text }?, 22 | element field { attribute name { 'department' }, text }*, 23 | element field { attribute name { 'sub_department' }, text }*, 24 | element field { attribute name { 'self' }, text }, 25 | element field { attribute name { 'subtitle' }, text }?, 26 | element field { attribute name { 'supertitle' }, text }?, 27 | element field { attribute name { 'title' }, text }?, 28 | element field { attribute name { 'body' }, text } 29 | } -------------------------------------------------------------------------------- /dev.cfg: -------------------------------------------------------------------------------- 1 | [buildout] 2 | extends = buildout.cfg 3 | parts += 4 | solr-server 5 | solr-schema 6 | solr-conf 7 | tests 8 | 9 | [api-wsgi] 10 | app_name = api_dev 11 | 12 | [doc-wsgi] 13 | app_name = doc_dev 14 | 15 | [solr-package] 16 | recipe = gocept.download 17 | url = http://archive.apache.org/dist/lucene/solr/3.6.2/apache-solr-3.6.2.tgz 18 | md5sum = e9c51f51265b070062a9d8ed50b84647 19 | 20 | [solr-schema] 21 | recipe = collective.recipe.rsync 22 | source = ${buildout:directory}/src/zeit/api/schemas/schema.xml 23 | target = ${buildout:directory}/parts/solr-server/solr/conf/schema.xml 24 | 25 | [solr-conf] 26 | recipe = collective.recipe.rsync 27 | source = ${buildout:directory}/src/zeit/api/schemas/solrconfig.xml 28 | target = ${buildout:directory}/parts/solr-server/solr/conf/solrconfig.xml 29 | 30 | [solr-server] 31 | recipe = collective.recipe.solrinstance 32 | solr-location = ${solr-package:location} 33 | index = name:uid type:string indexed:true stored:true required:true 34 | schema-template = ${buildout:directory}/src/zeit/api/schemas/schema_.xml 35 | vardir = ${deployment:root}/var/${:_buildout_section_name_} 36 | logdir = ${deployment:log-directory} 37 | script = ${deployment:rc-directory}/${:_buildout_section_name_} 38 | autoCommitMaxTime = 1000 39 | 40 | [tests] 41 | recipe = pbp.recipe.noserunner 42 | eggs = ${eggs:eggs} 43 | defaults = -v --nocapture -------------------------------------------------------------------------------- /LICENCE.md: -------------------------------------------------------------------------------- 1 | Copyright (c) 2013 by ZEIT ONLINE GmbH and contributors. 2 | 3 | All rights reserved. 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | * Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | * Neither the name of the ZEIT ONLINE GmbH nor the names of its contributors 16 | may be used to endorse or promote products derived from this software 17 | without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 20 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL ZEIT ONLINE BE LIABLE FOR ANY DIRECT, 23 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 24 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 26 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 27 | OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 28 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -------------------------------------------------------------------------------- /src/zeit/api/schemas/database.sql: -------------------------------------------------------------------------------- 1 | /* 2 | zeit.api.schemas.database 3 | ~~~~~~~~~~~~~ 4 | 5 | These are the initialization statements for the main SQLite database. 6 | 7 | Copyright: (c) 2013 by ZEIT ONLINE. 8 | License: BSD, see LICENSE.md for more details. 9 | */ 10 | 11 | CREATE TABLE IF NOT EXISTS author 12 | ( 13 | href CHAR(256), 14 | id CHAR(256) NOT NULL PRIMARY KEY, 15 | type CHAR(32) NOT NULL, 16 | uri CHAR(288) NOT NULL, 17 | value CHAR(256) NOT NULL 18 | ); 19 | 20 | CREATE TABLE IF NOT EXISTS client 21 | ( 22 | api_key CHAR(64) NOT NULL PRIMARY KEY, 23 | tier CHAR(32) NOT NULL, 24 | name CHAR(128), 25 | email CHAR(128), 26 | requests UNSIGNED INTEGER, 27 | reset UNSIGNED INTEGER 28 | ); 29 | 30 | CREATE TABLE IF NOT EXISTS department 31 | ( 32 | href CHAR(128), 33 | id CHAR(64) NOT NULL PRIMARY KEY, 34 | parent CHAR(64), 35 | uri CHAR(96) NOT NULL, 36 | value CHAR(64) NOT NULL, 37 | FOREIGN KEY(parent) REFERENCES department(id) 38 | ); 39 | 40 | CREATE TABLE IF NOT EXISTS keyword 41 | ( 42 | href CHAR(128), 43 | id CHAR(64) NOT NULL PRIMARY KEY, 44 | lexical CHAR(64) NOT NULL, 45 | score UNSIGNED INTEGER, 46 | type CHAR(32) NOT NULL, 47 | uri CHAR(96) NOT NULL, 48 | value CHAR(64) NOT NULL 49 | ); 50 | 51 | CREATE TABLE IF NOT EXISTS product 52 | ( 53 | href CHAR(128), 54 | id CHAR(32) NOT NULL PRIMARY KEY, 55 | uri CHAR(64) NOT NULL, 56 | value CHAR(64) NOT NULL 57 | ); 58 | 59 | CREATE TABLE IF NOT EXISTS series 60 | ( 61 | href CHAR(128), 62 | id CHAR(64) NOT NULL PRIMARY KEY, 63 | name CHAR(128) NOT NULL, 64 | uri CHAR(96) NOT NULL, 65 | value CHAR(128) NOT NULL 66 | ); -------------------------------------------------------------------------------- /src/zeit/api/templates/licence.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Licence{% endblock %} 3 | {% block docBody %} 4 | 5 |

6 | ZEIT ONLINE stellt die API (Application Programming Interface) als 7 | öffentliche BETA-Version zur Verfügung. Die API umfasst die Inhalte des 8 | ZEIT Archivs seit 1946 sowie Inhalte von ZEIT ONLINE in maschinenlesbarer 9 | Form. Mit der API sollen nicht-kommerzielle Erforschung, Analyse und 10 | Visualisierung der Inhalte erleichtert werden. Umsetzungen auf Basis der 11 | API möchten wir sehr gerne auf diesen Seiten vorstellen, bitte informieren 12 | Sie uns unter api@zeit.de. 13 |

14 |

15 | Die Speicherung und Ausgabe des Volltexts von Artikeln ist zum derzeitigen 16 | Stand nicht möglich. Bitte beachten Sie, dass die Beiträge unserer Autoren 17 | dem Schutz des Urheberrechts unterliegen. Falls Sie ein Projekt auf 18 | Grundlage von Volltextübernahmen planen, möchten wir Sie bitten, mit uns 19 | Kontakt aufzunehmen. Es gelten die 20 | 21 | Allgemeinen Nutzungsbedingungen von ZEIT ONLINE. Für Rückfragen stehen 22 | wir gern zur Verfügung. 23 |

24 |

25 | Wir wünschen einen fruchtbaren Dialog mit allen an der API Interessierten. 26 |
Für Vorschläge, technische Fragen oder Anregungen erreichen Sie uns unter 27 | api@zeit.de oder 28 | 29 | @zeitonline_dev, bei Fragen zur kommerziellen Verwendung und Lizenzierung 30 | unter online-syndication@zeit.de. 31 |

32 | 33 | {% endblock %} 34 | -------------------------------------------------------------------------------- /src/zeit/api/access.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.access 4 | ~~~~~~~~~~~~~~~ 5 | 6 | This module provides functionalities for regulating API access. 7 | 8 | Copyright: (c) 2013 by ZEIT ONLINE. 9 | License: BSD, see LICENSE.md for more details. 10 | """ 11 | import time 12 | 13 | from flask import g, current_app as current_app 14 | 15 | from . import exception 16 | 17 | 18 | class Verifictaion(object): 19 | """Context manager class for API key validation and usage tracking.""" 20 | 21 | def __enter__(self): 22 | """Verify key and quota. Raise exception if either fails.""" 23 | if not hasattr(g, 'api_key'): 24 | raise exception.unauthorized() 25 | 26 | query = 'SELECT requests,reset,tier FROM client WHERE api_key=?;' 27 | client = g.db.execute(query, (g.api_key,)).fetchone() 28 | 29 | if not client: 30 | raise exception.unauthorized() 31 | 32 | requests = client[0] 33 | reset = client[1] 34 | quota = current_app.config['ACCESS_TIERS'][client[2]] 35 | timeframe = current_app.config['ACCESS_TIMEFRAME'] 36 | 37 | if (int(time.time()) - reset) / timeframe > 0: 38 | reset += ((int(time.time()) - reset) / timeframe) * timeframe 39 | requests = 0 40 | query = ('UPDATE OR IGNORE client SET reset=?, requests=? ' 41 | 'WHERE api_key=?;') 42 | g.db.execute(query, (reset, requests, g.api_key)) 43 | 44 | if quota <= requests: 45 | raise exception.too_many_requests() 46 | 47 | def __exit__(self, type, value, traceback): 48 | """Increase request counter before closing context.""" 49 | query = ('UPDATE OR IGNORE client SET requests=requests + 1 ' 50 | 'WHERE api_key=?;') 51 | g.db.execute(query, (g.api_key,)) 52 | -------------------------------------------------------------------------------- /src/zeit/api/settings.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.settings 4 | ~~~~~~~~~~~~~~~~ 5 | 6 | This module contains config classes for different build scenarios. 7 | 8 | Copyright: (c) 2013 by ZEIT ONLINE. 9 | License: BSD, see LICENSE.md for more details. 10 | """ 11 | 12 | 13 | class Config(object): 14 | 15 | ACCESS_TIMEFRAME = 86400 16 | ACCESS_TIERS = {'free': 10000, 'pro': 50000, 'max': 1000000} 17 | 18 | SCHEMA = '/schemas/database.sql' 19 | DATABASE = '/var/lib/zon-api/data.db' 20 | PRODUCT_ALPHABET = '' 21 | SERIES_ALPHABET = '' 22 | KEYWORD_ALPHABET = '' 23 | DEPARTMENT_ALPHABET = '' 24 | RECAPTCHA_PRIVATE_KEY = '' 25 | RECAPTCHA_PUBLIC_KEY = '' 26 | 27 | try: 28 | import private 29 | PRODUCT_ALPHABET = private.PRODUCT_ALPHABET 30 | SERIES_ALPHABET = private.SERIES_ALPHABET 31 | KEYWORD_ALPHABET = private.KEYWORD_ALPHABET 32 | DEPARTMENT_ALPHABET = private.DEPARTMENT_ALPHABET 33 | except: 34 | pass 35 | 36 | 37 | class ProductionConfig(Config): 38 | 39 | DOC_URL = 'https://developer.zeit.de' 40 | API_URL = 'https://api.zeit.de' 41 | SOLR_URL = 'http://127.0.0.1:8983/solr' 42 | 43 | try: 44 | import private 45 | RECAPTCHA_PRIVATE_KEY = private.RECAPTCHA_PRIVATE_PROD 46 | RECAPTCHA_PUBLIC_KEY = private.RECAPTCHA_PUBLIC_PROD 47 | except: 48 | pass 49 | 50 | 51 | class DevelopmentConfig(Config): 52 | 53 | DOC_URL = 'http://localhost:9090' 54 | API_URL = 'http://localhost:9091' 55 | SOLR_URL = 'http://developer.zeit.de:8983/solr' 56 | 57 | try: 58 | import private 59 | RECAPTCHA_PRIVATE_KEY = private.RECAPTCHA_PRIVATE_DEVEL 60 | RECAPTCHA_PUBLIC_KEY = private.RECAPTCHA_PUBLIC_DEVEL 61 | except: 62 | pass 63 | 64 | 65 | class LocalConfig(DevelopmentConfig): 66 | 67 | API_PORT = 5000 68 | DOC_PORT = 5001 69 | SERVERNAME = '127.0.0.1' 70 | API_URL = 'http://%s:%d' % (SERVERNAME, API_PORT) 71 | DOC_URL = 'http://%s:%d' % (SERVERNAME, DOC_PORT) 72 | 73 | 74 | class TestingConfig(LocalConfig): 75 | 76 | TESTING = True 77 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Content-API 2 | 3 | ZEIT ONLINE content API - A [flask](http://flask.pocoo.org/) – 4 | [Solr](http://lucene.apache.org/solr/) middleware 5 | 6 | 7 | ## Frequent questions 8 | 9 | ### What is this? 10 | This is the ZEIT ONLINE content API project as available at 11 | https://developer.zeit.de. It enables you to access articles and corresponding 12 | metadata from the ZEIT newspaper archive, as well as recent articles from ZEIT 13 | and ZEIT ONLINE. 14 | 15 | ### Is it ready? 16 | It is still in public beta. We are working on improving the quality of our data 17 | as well as the stability of our code. You are welcome to test and experiment 18 | with the API, take a look at the code, file a bug report or request a feature. 19 | 20 | ### Where are the docs? 21 | You can find the documentation at our developer portal over at 22 | https://developer.zeit.de 23 | 24 | ### Can I run the API locally? 25 | Yes. It is tailored to the infrastructure we have here at ZEIT ONLINE, though. 26 | So it might not be of too much use for other scenarios and will require some 27 | adaptation. See below for instructions. 28 | 29 | ###How can I get in touch? 30 | We would love to hear your ideas and feedback. Join the discussion in the 31 | [issues section](http://github.com/ZeitOnline/content-api/issues), contact us 32 | on Twitter at [zeitonline_dev](http://twitter.com/zeitonline_dev) or send an 33 | Email to [api@zeit.de](mailto:api@zeit.de). 34 | 35 | 36 | ## Getting started 37 | 38 | Check out the repository, change to the project folder and then bootstrap the 39 | project like this: 40 | ```bash 41 | $ ./bootstrap.sh # requires python2.7 and virtualenv to be installed 42 | ``` 43 | 44 | Run the server like this: 45 | ```bash 46 | $ bin/api 47 | $ bin/doc 48 | ``` 49 | 50 | ## Local solr 51 | 52 | Run buildout with the development configuration: 53 | ```bash 54 | $ bin/buildout -c dev.cfg 55 | ``` 56 | 57 | This will install dependencies, generate executables for the API, the developer 58 | portal and the testsuite and download a Solr package. To start the Solr 59 | locally, switch to parts/solr-server and enter: 60 | ```bash 61 | $ java -jar start.jar 62 | ``` 63 | 64 | With the search server running, you can now start the testsuite: 65 | ```bash 66 | $ bin/tests 67 | ``` 68 | -------------------------------------------------------------------------------- /src/zeit/api/application.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.application 4 | ~~~~~~~~~~~~~~~~~~~~ 5 | 6 | This module contains factory methods, that return WSGI compatible app 7 | instances configured for deployment or testing, and a local run method, 8 | that does not require a full WSGI server. 9 | 10 | Copyright: (c) 2013 by ZEIT ONLINE. 11 | License: BSD, see LICENSE.md for more details. 12 | """ 13 | 14 | import flask 15 | 16 | from . import settings, blueprints 17 | 18 | 19 | def make_app(blueprint, config): 20 | """Configure a flask instance with a given blueprint and configuration.""" 21 | app = flask.Flask(import_name=__name__) 22 | app.register_blueprint(blueprint) 23 | app.url_map.strict_slashes = False 24 | app.config.from_object(config) 25 | return app 26 | 27 | 28 | def run_local_api(): 29 | """Run an api server instance on a local development server.""" 30 | cfg = settings.LocalConfig() 31 | app = make_app(blueprints.api_server, settings.LocalConfig) 32 | app.run(host=cfg.SERVERNAME, port=cfg.API_PORT, debug=True) 33 | 34 | 35 | def run_local_doc(): 36 | """Runs a developer portal instance on a local development server.""" 37 | cfg = settings.LocalConfig() 38 | app = make_app(blueprints.developer_portal, settings.LocalConfig) 39 | app.run(host=cfg.SERVERNAME, port=cfg.DOC_PORT, debug=True) 40 | 41 | 42 | def test_client_factory(): 43 | """Return a client instance for automated testing.""" 44 | app = make_app(blueprints.api_server, settings.TestingConfig) 45 | return app.test_client() 46 | 47 | 48 | def api_factory(global_config, **local_conf): 49 | """Return an api server instance configured for production.""" 50 | return make_app(blueprints.api_server, settings.ProductionConfig) 51 | 52 | 53 | def doc_factory(global_config, **local_conf): 54 | """Return a developer portal instance configured for production.""" 55 | return make_app(blueprints.developer_portal, settings.ProductionConfig) 56 | 57 | 58 | def api_dev_factory(global_config, **local_conf): 59 | """Return an api server instance configured for development.""" 60 | return make_app(blueprints.api_server, settings.DevelopmentConfig) 61 | 62 | 63 | def doc_dev_factory(global_config, **local_conf): 64 | """Return a developer portal instance configured for development.""" 65 | return make_app(blueprints.developer_portal, settings.DevelopmentConfig) 66 | -------------------------------------------------------------------------------- /src/zeit/api/util.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.util 4 | ~~~~~~~~~~~~~ 5 | 6 | This module provides helper functions used throughout the application. 7 | 8 | Copyright: (c) 2013 by ZEIT ONLINE. 9 | License: BSD, see LICENSE.md for more details. 10 | """ 11 | 12 | import re 13 | import urllib 14 | import urlparse 15 | 16 | 17 | def append_to_csv(csv, new): 18 | """Add a new value to a string formatted, comma separted value list.""" 19 | 20 | if csv == '': 21 | return new 22 | arr = csv.split(',') 23 | arr.append(new) 24 | return ','.join(arr) 25 | 26 | 27 | def csv_to_list(csv): 28 | """Convert a csv string to an array, while ommitting empty entries.""" 29 | 30 | for val in csv.split(','): 31 | if val != '': 32 | yield val 33 | 34 | 35 | def dict_by_list(dic, arr): 36 | """Filter a dictionary by a list of valid keys.""" 37 | 38 | for key in dic: 39 | if key in arr: 40 | yield key, dic[key] 41 | 42 | 43 | def ensure_prefix(string, prefix): 44 | """Ensure, that a string is prefixed by another string.""" 45 | 46 | if string[:len(prefix)] == prefix: 47 | return string 48 | return prefix + string 49 | 50 | 51 | def iri_to_uri(iri): 52 | """Convert an Internationalized Resource Identifier to a URI.""" 53 | 54 | parts = urlparse.urlparse(iri) 55 | return urlparse.urlunparse( 56 | part.encode('idna') if parti == 1 else 57 | url_encode_non_ascii(part.encode('utf-8')) 58 | for parti, part in enumerate(parts) 59 | ) 60 | 61 | 62 | def save_xpath(element, xpath, fallback=''): 63 | """Safely return the first result of an xpath expression.""" 64 | 65 | try: 66 | return element.xpath(xpath)[0] 67 | except IndexError: 68 | return fallback 69 | 70 | 71 | def url_encode(data): 72 | """Safely encode a dictionary to a URL compatible string.""" 73 | 74 | param = dict() 75 | for key, val in data.iteritems(): 76 | if key == 'facet.field': 77 | param[key] = list(csv_to_list(val)) 78 | elif isinstance(val, int): 79 | param[key] = '%d' % val 80 | else: 81 | param[key] = val 82 | return urllib.urlencode(param, True) 83 | 84 | 85 | def url_encode_non_ascii(href): 86 | """URL-encode non ascii characters.""" 87 | 88 | function = lambda c: '%%%02x' % ord(c.group(0)) 89 | return re.sub('[\x80-\xFF]', function, href) 90 | -------------------------------------------------------------------------------- /src/zeit/api/templates/index.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}ZEIT ONLINE Content API{% endblock %} 3 | {% block docBody %} 4 |

5 |

Visualization by Gregor Aisch

6 |

7 |
8 |

9 | Willkommen zu der Beta-Version der ZEIT ONLINE Content API. 10 | Über diese Schnittstelle kann auf Inhalte und zugehörige Metadaten aus 11 | dem Archiv der ZEIT seit 1946 und von ZEIT ONLINE zugegriffen werden kann. 12 | Wir laden alle an Programmierung, Datenanalyse und Visualisierung 13 | Interessierten ein, den Index aus mehreren hunderttausenden Artikeln zu 14 | erkunden. Die Benutzung der Schnittstelle ist für nicht-kommerzielle 15 | Anwendungsfälle kostenlos. Bitte beachten Sie in jedem Falle die 16 | Nutzungsbedingungen. 17 |

18 |

19 | Um gleich mit dem Erstellen von Anwendungen oder Auswertungen zu beginnen, 20 | können Sie sich unter Quickstart 21 | einen API-Key freischalten lassen. Der 22 | Explorer ermöglicht Ihnen die 23 | Befragung der Schnittstelle über ein einfaches Web-Interface. Mehr über die 24 | Funktionen und Endpunkte der API erfahren Sie in der englischen 25 | Dokumentation. 26 |

27 |

35 |

36 |

37 | Welcome to the beta version of the ZEIT ONLINE content API. Via the API you 38 | can access articles and corresponding metadata from the ZEIT archive dating 39 | back to 1946 and from ZEIT ONLINE. We invite everybody interested in 40 | programming, data analysis and visualization to explore the index of 41 | hundreds of thousands articles. The API can be used for free for 42 | non-commercial use cases. Please refer to the 43 | terms of use (German only at the 44 | moment). 45 |

46 |

47 | To get started building apps or analysing data, just request an API key 48 | in our quickstart guide. The 49 | explorer will allow you to query 50 | the API via a simple web-interface. A full 51 | documentation of the endpoints and their capabilites is also available. 52 |

53 |

60 | 61 | {% endblock %} 62 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/series.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Series{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search all series

6 |

7 | This endpoint lets you search for journalistic series by name. An asterisk 8 | can serve as a wildcard or whitespace in your search query. 9 |

10 | 11 |

Endpoint

12 |

{{ api_url }}/series

13 | 14 |

Parameter

15 |


 16 |   
 17 |     
 18 |         
 19 |         
 20 |     
 21 |     
 22 |         
 23 |         
 24 |     
 25 |     
 26 |         
 27 |         
 28 |     
 29 | 
 30 |     
 31 |         
 32 |         
 33 |     
 34 |   q* the main search query
fieldsuri,value,href partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 35 |

36 | 37 |

Example

38 | 39 |

Request

40 |

GET /series?q=*lorem*&limit=1 HTTP/1.1
 41 | Host: {{ api_url }}
 42 | X-Authorization: abcdefg1234xyz56789
 43 |

44 | 45 |

Response

46 |

{
 47 |     "matches": [
 48 |       {
 49 |       "href": "http://www.zeit.de/serie/lorem-ipsum",
 50 |       "uri": "http://127.0.0.1:5000/api/series/lorem-ipsum",
 51 |       "value": "Lorem ipsum dolor set?"
 52 |       }
 53 |     ],
 54 |     "found": 7,
 55 |     "limit": 1,
 56 |     "offset": 0
 57 | }

58 | 59 |

60 | 61 |

Get series by ID

62 | 63 |

64 | This endpoint provides a pre-filtered search for all articles written for a 65 | specific series. Deeper queries, pagination and partial field selection can 66 | be used to narrow down the match list. 67 |

68 | 69 |

Endpoint

70 |

{{ api_url }}/series/{id}

71 | 72 |

Parameter

73 |


 74 |   
 75 |     
 76 |       
 77 |       
 78 |     
 79 |     
 80 |       
 81 |       
 82 |     
 83 |     
 84 |       
 85 |       
 86 |     
 87 |     
 88 |       
 89 |       
 90 |     
 91 |   q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 92 |

93 | 94 |

Example

95 | 96 |

Request

97 |

GET /series/lorem-ipsum?limit=1 HTTP/1.1
 98 | Host: {{ api_url }}
 99 | X-Authorization: abcdefg1234xyz56789
100 |

101 | 102 |

Response

103 |

{
104 |   "matches": [
105 |     {
106 |       "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
107 |         diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.",
108 |       "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.", 
109 |       "href": "http://www.zeit.de/dolorem/lorem-ipsum/2012-12/Lorem-ipsum-que",
110 |       "release_date": "2011-12-01T14:40:00.000Z", 
111 |       "uri": "{{ api_url }}/content/1111122299xxcc99aa", 
112 |       "supertitle": "Lorem Ipsum", 
113 |       "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing."
114 |       "teaser_text": "Sicilia que es una magnifica maestrae."
115 |     }
116 |   ],
117 |   "uri": "{{ api_url }}/series/lorem-ipsum",
118 |   "href": "http://www.zeit.de/series/lorem-ipsum",
119 |   "value": "Lorem ipsum dolor set?",
120 |   "limit": 1,
121 |   "offset": 0,
122 |   "found": 30
123 | }

124 | 125 | {% endblock %} 126 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/product.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Product{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search all products

6 | 7 |

8 | This endpoint lets you search for publication products by name. The product 9 | field of an article provides information about where the article was first 10 | published. An asterisk can serve as a wildcard or whitespace in your search 11 | query. 12 |

13 | 14 |

Endpoint

15 |

{{ api_url }}/product

16 | 17 |

Parameter

18 |


 19 |   
 20 |     
 21 |       
 22 |       
 23 |     
 24 |     
 25 |       
 26 |       
 27 |     
 28 |     
 29 |       
 30 |       
 31 |     
 32 |     
 33 |       
 34 |       
 35 |     
 36 |   q* the main search query
fieldsuri,value partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 37 |

38 | 39 |

Example

40 | 41 |

Request

42 |

GET /product?q=*tempor*&limit=2 HTTP/1.1
 43 | Host: {{ api_url }}
 44 | X-Authorization: abcdefg1234xyz56789
 45 |

46 | 47 |

Response

48 |

{
 49 |   "matches": [
 50 |    	{
 51 |       "uri": "http://127.0.0.1:5000/api/product/tpi",
 52 |       "value": "Tempores Inlinea"
 53 |    	},
 54 |    	{
 55 |       "uri": "http://127.0.0.1:5000/api/product/tem",
 56 |       "value": "TEMPORES"
 57 |   	}
 58 |   ],
 59 |   "found": 3,
 60 |   "limit": 2,
 61 |   "offset": 0
 62 | }

63 | 64 |

65 | 66 |

Get product by ID

67 | 68 |

69 | This endpoint provides a pre-filtered search for all articles published in a 70 | specific product. Deeper queries, pagination and partial field selection can 71 | be used to narrow down the match list. 72 |

73 | 74 |

Endpoint

75 |

{{ api_url }}/product/{id}

76 | 77 |

Parameter

78 |


 79 |   
 80 |     
 81 |       
 82 |       
 83 |     
 84 |     
 85 |       
 86 |       
 87 |     
 88 |     
 89 |       
 90 |       
 91 |     
 92 |     
 93 |       
 94 |       
 95 |     
 96 |   q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 97 |

98 | 99 |

Example

100 | 101 |

Request

102 |

GET /product/tpi?limit=1 HTTP/1.1
103 | Host: {{ api_url }}
104 | X-Authorization: abcdefg1234xyz56789
105 |

106 | 107 |

Response

108 |

{
109 |   "matches": [
110 |     {
111 |       "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
112 |         diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.",
113 |       "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.", 
114 |       "href": "http://www.zeit.de/dolorem/lorem-ipsum/2012-12/Lorem-ipsum-que", 
115 |       "release_date": "2011-12-01T14:40:00.000Z", 
116 |       "uri": "{{ api_url }}/content/1111122299xxcc99aa", 
117 |       "supertitle": "Lorem Ipsum", 
118 |       "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing."
119 |       "teaser_text": "Sicilia que es una magnifica maestrae."
120 |     }
121 |   ],
122 |   "uri": "{{ api_url }}/product/tpi",
123 |   "value": "Tempores Inlinea",
124 |   "limit": 1,
125 |   "offset": 0,
126 |   "found": 9156
127 | }

128 | {% endblock %} 129 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/author.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Author{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search all authors

6 |

7 | This endpoint lets you search for authors by their name. The result is a list 8 | of possible matches with a displayable value, a URI to an article overview 9 | within the API and, if available, a link to all articles by this author on 10 | www.zeit.de. 11 |

12 | 13 |

Endpoint

14 |

{{ api_url }}/author

15 | 16 |

Parameter

17 |


 18 |   
 19 |     
 20 |       
 21 |       
 22 |     
 23 |     
 24 |       
 25 |       
 26 |     
 27 |     
 28 |       
 29 |       
 30 |     
 31 |     
 32 |       
 33 |       
 34 |     
 35 |   q* main search query with asterisk as wildcard
fieldshref,id,type,uri,value partially select output fields
limit10 amount of matches to return
offset0 offset for the list of matches
 36 |

37 | 38 |

Example

39 | 40 |

Request

41 |

GET /author?q=James*Muster*&limit=1 HTTP/1.1
 42 | Host: {{ api_url }}
 43 | X-Authorization: abcdefg1234xyz56789
 44 |

45 | 46 |

Response

47 |

{
 48 |   "matches": [
 49 |     {
 50 |       "href": "http://www.zeit.de/autoren/J/James_Mustermann/index.xml",
 51 |       "type": "author",
 52 |       "id": "James-Mustermann",
 53 |       "value": "James Mustermann",
 54 |       "uri": "{{ api_url }}/author/James-Mustermann"
 55 |     }
 56 |   ], 
 57 |   "found": 3, 
 58 |   "limit": 1, 
 59 |   "offset": 0
 60 | }

61 | 62 |

63 | 64 |

Get author by ID

65 | 66 |

67 | This endpoint provides a pre-filtered search for all articles written by a 68 | specific author. Deeper queries, pagination and partial field selection can 69 | be used to narrow down the match list. 70 |

71 | 72 |

Endpoint

73 |

{{ api_url }}/author/{id}

74 | 75 |

Parameter

76 |


 77 |   
 78 |     
 79 |       
 80 |       
 81 |     
 82 |     
 83 |       
 84 |       
 85 |     
 86 |     
 87 |       
 88 |       
 89 |     
 90 |     
 91 |       
 92 |       
 93 |     
 94 |   q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 95 |

96 | 97 |

Example

98 | 99 |

Request

100 |

GET /author/Jasmine-Mustermann?limit=1 HTTP/1.1
101 | Host: {{ api_url }}
102 | X-Authorization: abcdefg1234xyz56789
103 |

104 | 105 |

Response

106 |

{
107 |   "value": "Jasmine Mustermann", 
108 |   "matches": [
109 |     {
110 |       "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
111 |         sed diam nonumy eirmod tempor invidunt ut labore et dolore magna.", 
112 |       "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.", 
113 |       "href": "http://www.zeit.de/department/sub/2012-12/Lorem-ipsum", 
114 |       "release_date": "2011-12-01T14:40:00.000Z", 
115 |       "uri": "{{ api_url }}/content/1111122299xxcc99aa", 
116 |       "supertitle": "Lorem Ipsum", 
117 |       "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing."
118 |     }
119 |   ], 
120 |   "uri": "{{ api_url }}/author/Jasmine-Mustermann",
121 |   "type": "author",
122 |   "limit": 1, 
123 |   "offset": 0, 
124 |   "found": 12
125 | }

126 | 127 | {% endblock %} 128 | -------------------------------------------------------------------------------- /src/zeit/api/exception.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.exception 4 | ~~~~~~~~~~~~~~~~~~ 5 | 6 | This module contains custom JSON exceptions. Not to be confused with the 7 | similarly named flask module 'exceptions'. Exceptions correspond to 8 | standard HTTP status codes. 9 | 10 | Copyright: (c) 2013 by ZEIT ONLINE. 11 | License: BSD, see LICENSE.md for more details. 12 | """ 13 | 14 | from flask.exceptions import JSONHTTPException 15 | from werkzeug.exceptions import (escape, NotFound, MethodNotAllowed, 16 | Unauthorized, BadRequest, InternalServerError, ServiceUnavailable) 17 | from flask import request 18 | 19 | 20 | class JSONTooManyRequests(JSONHTTPException): 21 | code = 429 22 | description = 'You have reached your request quota.' 23 | 24 | @property 25 | def name(self): 26 | return 'Too Many Requests' 27 | 28 | 29 | class JSONUnauthorized(JSONHTTPException, Unauthorized): 30 | description = 'The provided api key seems to be invalid.' 31 | 32 | 33 | class JSONEndpointNotFound(JSONHTTPException, NotFound): 34 | description = 'The requested endpoint is not defined.' 35 | 36 | 37 | class JSONResourceNotFound(JSONHTTPException, NotFound): 38 | description = 'The requested resource can not be found.' 39 | 40 | 41 | class JSONMethodNotAllowed(JSONHTTPException, MethodNotAllowed): 42 | def get_description(self, environ): 43 | m = escape(environ.get('REQUEST_METHOD', 'GET')) 44 | return 'The method %s is not allowed for the requested URL.' % m 45 | 46 | 47 | class JSONBadRequest(JSONHTTPException, BadRequest): 48 | description = 'The request cannot be fulfilled due to bad syntax.' 49 | 50 | 51 | class JSONInternalServerError(JSONHTTPException, InternalServerError): 52 | description = 'Due to an internal error the request could not be fulfilled.' 53 | 54 | 55 | class JSONServiceUnavailable(JSONHTTPException, ServiceUnavailable): 56 | description = 'The service is currently unavailable.' 57 | 58 | 59 | def too_many_requests(error=None): 60 | excp = JSONTooManyRequests() 61 | message = '%d: %s' % (excp.code, error or excp.description) 62 | print >> request.environ['wsgi.errors'], message 63 | return excp 64 | 65 | 66 | def unauthorized(error=None): 67 | excp = JSONUnauthorized() 68 | message = '%d: %s' % (excp.code, error or excp.description) 69 | print >> request.environ['wsgi.errors'], message 70 | return excp 71 | 72 | 73 | def endpoint_not_found(error=None): 74 | excp = JSONEndpointNotFound() 75 | message = '%d: %s' % (excp.code, error or excp.description) 76 | print >> request.environ['wsgi.errors'], message 77 | return excp 78 | 79 | 80 | def resource_not_found(error=None): 81 | excp = JSONResourceNotFound() 82 | message = '%d: %s' % (excp.code, error or excp.description) 83 | print >> request.environ['wsgi.errors'], message 84 | return excp 85 | 86 | 87 | def method_not_allowed(error=None): 88 | excp = JSONMethodNotAllowed() 89 | message = '%d: %s' % (excp.code, error or excp.description) 90 | print >> request.environ['wsgi.errors'], message 91 | return excp 92 | 93 | 94 | def bad_request(error=None): 95 | excp = JSONBadRequest() 96 | message = '%d: %s' % (excp.code, error or excp.description) 97 | print >> request.environ['wsgi.errors'], message 98 | return excp 99 | 100 | 101 | def internal_server_error(error=None): 102 | excp = JSONInternalServerError() 103 | message = '%d: %s' % (excp.code, error or excp.description) 104 | print >> request.environ['wsgi.errors'], message 105 | return excp 106 | 107 | 108 | def service_unavailable(error=None): 109 | excp = JSONServiceUnavailable() 110 | message = '%d: %s' % (excp.code, error or excp.description) 111 | print >> request.environ['wsgi.errors'], message 112 | return excp 113 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/department.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Department{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search all departments

6 | 7 |

8 | Departments correlate to the sections of our homepage and to those of the 9 | printed issues. There are top level departments and sub-departments. Both are 10 | accessible via this endpoint. Sub-departments have a link to their parent 11 | attached to them. The query expects an astisk for wildcards and whitespaces. 12 |

13 | 14 |

Endpoint

15 |

{{ api_url }}/department

16 | 17 |

Parameter

18 |


 19 |   
 20 |     
 21 |       
 22 |       
 23 |     
 24 |     
 25 |       
 26 |       
 27 |     
 28 |     
 29 |       
 30 |       
 31 |     
 32 |     
 33 |       
 34 |       
 35 |     
 36 |   q* the main search query
fieldsuri,value,parent,href partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 37 |

38 | 39 |

Example

40 | 41 |

Request

42 |

GET /department?q=*lorem*&limit=1 HTTP/1.1
 43 | Host: {{ api_url }}
 44 | X-Authorization: abcdefg1234xyz56789
 45 |

46 | 47 |

Response

48 |

{
 49 |     "matches": [
 50 |         {
 51 |             "href": "http://www.zeit.de/dolorem/index",
 52 |             "uri": "http://127.0.0.1:5000/api/department/dolorem",
 53 |             "value": "Dolorem"
 54 |         }
 55 |     ],
 56 |     "found": 3,
 57 |     "limit": 1,
 58 |     "offset": 0
 59 | }

60 | 61 |

62 | 63 |

Get department by ID

64 | 65 |

66 | This endpoint provides a pre-filtered search for all articles belonging to a 67 | specific department. Deeper queries, pagination and partial field selection 68 | can be used to narrow down the match list. 69 |

70 | 71 |

Endpoint

72 |

{{ api_url }}/department/{id}

73 | 74 |

Parameter

75 |


 76 |   
 77 |     
 78 |       
 79 |       
 80 |     
 81 |     
 82 |       
 83 |       
 84 |     
 85 |     
 86 |       
 87 |       
 88 |     
 89 |     
 90 |       
 91 |       
 92 |     
 93 |   q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 94 |

95 | 96 |

Example

97 | 98 |

Request

99 |

GET /department/lorem-ipsum?limit=1 HTTP/1.1
100 | Host: {{ api_url }}
101 | X-Authorization: abcdefg1234xyz56789
102 |

103 | 104 |

Response

105 |

{
106 |   "matches": [
107 |     {
108 |       "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
109 |         diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.", 
110 |       "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.", 
111 |       "href": "http://www.zeit.de/dolorem/lorem-ipsum/2012-12/Sit-amet",
112 |       "release_date": "2011-12-01T14:40:00.000Z", 
113 |       "uri": "{{ api_url }}/content/1111122299xxcc99aa", 
114 |       "supertitle": "Lorem Ipsum", 
115 |       "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing."
116 |       "teaser_text": "Sicilia que es una magnifica maestrae."
117 |     }
118 |   ],
119 |   "uri": "{{ api_url }}/department/lorem-ipsum",
120 |   "parent": "{{ api_url }}/department/dolorem",
121 |   "href": "http://www.zeit.de/dolorem/lorem-ipsum/index",
122 |   "value": "Lorem Ipsum",
123 |   "limit": 1,
124 |   "offset": 0,
125 |   "found": 312
126 | }

127 | 128 | {% endblock %} 129 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/keyword.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Keyword{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search all keywords

6 | 7 |

8 | This endpoint lets you search for keywords that semantically summarize 9 | articles. An asterisk can serve as a wildcard or whitespace in your search 10 | query. Keywords are weighted by their overall frequency with a score from 0 11 | to 100. Possible keyword types are: location, person, organisation or issue. 12 |

13 | 14 |

Endpoint

15 |

{{ api_url }}/keyword

16 | 17 |

Parameter

18 |


 19 |   
 20 |     
 21 |       
 22 |       
 23 |     
 24 |     
 25 |       
 28 |       
 29 |     
 30 |     
 31 |       
 32 |       
 33 |     
 34 |     
 35 |       
 36 |       
 37 |     
 38 |   q* the main search query

 26 |         fieldsuri,value,lexical,type,score,href
 27 |       partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 39 |

40 | 41 |

Example

42 | 43 |

Request

44 |

GET /keyword?q=*rom*&limit=1 HTTP/1.1
 45 | Host: {{ api_url }}
 46 | X-Authorization: abcdefg1234xyz56789
 47 |

48 | 49 |

Response

50 |

{
 51 |     "matches": [
 52 |         {
 53 |             "href": "http://www.zeit.de/schlagworte/orte/romanium/index",
 54 |             "score": 75,
 55 |             "type": "location",
 56 |             "uri": "{{ api_url }}/keyword/romanium",
 57 |             "value": "Romanium"
 58 |         }
 59 |     ],
 60 |     "found": 116,
 61 |     "limit": 1,
 62 |     "offset": 0
 63 | }

64 | 65 |

66 | 67 |

Get keyword by ID

68 | 69 |

70 | This endpoint provides a pre-filtered search for all articles tagged with a 71 | specific keyword. Deeper queries, pagination and partial field selection can 72 | be used to narrow down the match list. 73 |

74 | 75 |

Endpoint

76 |

{{ api_url }}/author/{id}

77 | 78 |

Parameter

79 |


 80 | 
 81 | 
 82 |     
 83 |     
 84 | 
 85 | 
 86 |     
 87 |     
 88 | 
 89 | 
 90 |     
 91 |     
 92 | 
 93 | 
 94 |     
 95 |     
 96 | 
 97 | q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 98 |

99 | 100 |

Example

101 | 102 |

Request

103 |

GET /keyword/jane-mustermann?limit=1 HTTP/1.1
104 | Host: {{ api_url }}
105 | X-Authorization: abcdefg1234xyz56789
106 |

107 | 108 |

Response

109 |

{
110 |   "matches": [
111 |     {
112 |       "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
113 |         diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.", 
114 |       "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.", 
115 |       "href": "http://www.zeit.de/dolorem/lorem-ipsum/2012-12/Lorem-ipsum-dolor", 
116 |       "release_date": "2011-12-01T14:40:00.000Z", 
117 |       "uri": "{{ api_url }}/content/1111122299xxcc99aa", 
118 |       "supertitle": "Lorem Ipsum", 
119 |       "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing."
120 |       "teaser_text": "Sicilia que es una magnifica maestrae."
121 |     }
122 |   ],
123 |   "uri": "{{ api_url }}/keyword/jane-mustermann",
124 |   "href": "http://www.zeit.de/schlagworte/personen/jane-mustermann/index",
125 |   "value": "Jane Mustermann",
126 |   "lexical": "Mustermann, Jane"
127 |   "type": "person",
128 |   "score": 75,
129 |   "limit": 1,
130 |   "offset": 0,
131 |   "found": 6
132 | }

133 | 134 | {% endblock %} 135 | -------------------------------------------------------------------------------- /src/zeit/api/metadata.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.metadata 4 | ~~~~~~~~~~~~~~~~~ 5 | 6 | This module contains methods that maintain metadata entities by parsing XML 7 | files and updating the API's SQLite database. 8 | 9 | Copyright: (c) 2013 by ZEIT ONLINE. 10 | License: BSD, see LICENSE.md for more details. 11 | """ 12 | 13 | import urllib 14 | 15 | from flask import g, current_app 16 | from lxml import etree 17 | 18 | from .util import iri_to_uri, save_xpath 19 | 20 | 21 | def __update_product(product): 22 | """Update the given product entity.""" 23 | product_id = save_xpath(product, './@id').lower() 24 | uri = '%s/product/%s' % (current_app.config['API_URL'], product_id) 25 | value = save_xpath(product, 'text()') 26 | href = save_xpath(product, './@href') 27 | query = 'REPLACE INTO product VALUES (?, ?, ?, ?);' 28 | g.db.execute(query, (href, product_id, uri, value)) 29 | 30 | 31 | def __update_series(series): 32 | """Update the given series entity.""" 33 | series_id = save_xpath(series, './@url') 34 | uri = '%s/series/%s' % (current_app.config['API_URL'], series_id) 35 | value = save_xpath(series, './@title') 36 | name = save_xpath(series, './@serienname') 37 | query = 'REPLACE INTO series VALUES (?, ?, ?, ?, ?);' 38 | href = 'http://www.zeit.de/serie/%s' % series_id 39 | g.db.execute(query, (href, series_id, name, uri, value)) 40 | 41 | 42 | def __update_keyword(keyword, ranks, types): 43 | """Update the given keyword entity.""" 44 | kw_id = save_xpath(keyword, './@url_value') 45 | uri = '%s/keyword/%s' % (current_app.config['API_URL'], kw_id) 46 | value = save_xpath(keyword, 'text()') 47 | lexical = save_xpath(keyword, './@lexical_value') 48 | kw_type = save_xpath(keyword, './@type') 49 | kw_type = 'subject' if kw_type in ['free', 'topic'] else kw_type.lower() 50 | score = (ranks.index(int(save_xpath(keyword, './@freq'))) + 1) 51 | score = int(100.0 / len(ranks) * score) 52 | href = 'http://www.zeit.de/schlagworte/%s/%s/index' % (types[kw_type], kw_id) 53 | query = 'REPLACE INTO keyword VALUES (?, ?, ?, ?, ?, ?, ?);' 54 | g.db.execute(query, (href, kw_id, lexical, score, kw_type, uri, value)) 55 | 56 | 57 | def __update_department(department): 58 | """Update the given department entity.""" 59 | dept_id = save_xpath(department, './@label') 60 | if dept_id in ['startseite']: 61 | return 62 | uri = '%s/department/%s' % (current_app.config['API_URL'], dept_id) 63 | value = save_xpath(department, 'text()') 64 | href = save_xpath(department, './@href')[19:].split('/', 1)[0] 65 | parent = href if href != dept_id else '' 66 | path = parent + '/' + dept_id if parent else dept_id 67 | href = 'http://www.zeit.de/%s/index' % path 68 | query = 'REPLACE INTO department VALUES (?, ?, ?, ?, ?);' 69 | g.db.execute(query, (href, dept_id, parent, uri, value)) 70 | 71 | 72 | def __update_author(author): 73 | """Update the given author entity.""" 74 | value = save_xpath(author, './@name') 75 | author_id = value.replace(' ', '-') 76 | uri = '%s/author/%s' % (current_app.config['API_URL'], author_id) 77 | initial = value.split(' ')[-1] or 'A' 78 | href_raw = 'http://www.zeit.de/autoren/%s/%s/index.xml' 79 | href = href_raw % (initial[0], value.replace(' ', '_')) 80 | href = href if urllib.urlopen(iri_to_uri(href)).getcode() == 200 else '' 81 | query = 'REPLACE INTO author VALUES (?, ?, ?, ?, ?);' 82 | g.db.execute(query, (href, author_id, 'author', uri, value)) 83 | 84 | 85 | def update(): 86 | """Update metadata of all categories and write changes to database.""" 87 | products = current_app.config['PRODUCT_ALPHABET'] 88 | for p in etree.parse(products).xpath('//product'): 89 | __update_product(p) 90 | 91 | series = current_app.config['SERIES_ALPHABET'] 92 | for s in etree.parse(series).xpath('//series'): 93 | print s 94 | __update_series(s) 95 | 96 | keywords = current_app.config['KEYWORD_ALPHABET'] 97 | parsed_keywords = etree.parse(keywords).xpath('//tag') 98 | ranks = sorted(set(int(save_xpath(k, './@freq')) for k in parsed_keywords)) 99 | types = {'location': 'orte', 'person': 'personen', 'subject': 'themen', 100 | 'organization': 'organisationen'} 101 | for k in parsed_keywords: 102 | print k 103 | __update_keyword(k, ranks, types) 104 | 105 | depts = current_app.config['DEPARTMENT_ALPHABET'] 106 | for d in etree.parse(depts).xpath('/lists/list[@id="sitemap"]//link'): 107 | print d 108 | __update_department(d) 109 | 110 | url = '/select?q=*:*&facet=true&facet.field=author' 111 | url += '&facet.limit=1000000&rows=0&facet.mincount=1' 112 | authors = current_app.config['SOLR_URL'] + url 113 | for a in etree.parse(authors).xpath('//lst[@name="author"]/int'): 114 | print a 115 | __update_author(a) 116 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs/content.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Content{% endblock %} 3 | {% block docBody %} 4 | 5 |

Search for content

6 | 7 |

8 | This endpoint exposes an unfiltered search for articles. You can set search 9 | queries, paginate, sort and partially select the fields, that should be 10 | returned. Articles, that match your query, are returned in the 11 | matches array with a reduced set of meta data. The full set of data 12 | is only available at /content/{id}. 13 |

14 | 15 |

Endpoint

16 |

{{ api_url }}/content

17 | 18 |

Parameter

19 |


 20 |     
 21 |         
 22 |            
 23 |             
 24 |         
 25 |         
 26 |             
 27 |             
 28 |         
 29 |         
 30 |             
 31 |             
 32 |         
 33 |         
 34 |             
 35 |             
 36 |         
 37 |     q*:* the main search query
fields* partially select output fields
limit10 limit the amount of matches to return
offset0 offset for the list of matches
 38 |

39 | 40 |

Example

41 | 42 |

Request

43 |

GET /content?q=dolore&limit=1 HTTP/1.1
 44 | Host: {{ api_url }}
 45 | X-Authorization: abcdefg1234xyz56789
 46 |

47 | 48 |

Response

49 |

{
 50 |   "matches": [
 51 |     {
 52 |         "subtitle": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
 53 |             sed diam nonumy eirmod tempor invidunt.",
 54 |         "uuid": "1111122299xxcc99aa", 
 55 |         "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
 56 |         "href": "http://www.zeit.de/lorem/ipsum/2012-12/Lorem-ipsum-dolor-sit",
 57 |         "release_date": "2011-12-01T14:40:00.000Z", 
 58 |         "uri": "{{ api_url }}/content/1111122299xxcc99aa",
 59 |         "snippet": "tempor invidunt ut labore et dolore magna aliquyam
 60 |             erat, sed diam voluptua"
 61 |         "supertitle": "Lorem Ipsum", 
 62 |         "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing.",
 63 |         "teaser_text": "Stet clita kasd gubergren, no sea takimata sanctus est
 64 |             Lorem ipsum dolor sit amet."
 65 |     }
 66 | ],
 67 |   "found": 148,
 68 |   "limit": 1,
 69 |   "offset": 0
 70 | }

71 | 72 |

73 | 74 |

Get content by ID

75 | 76 |

77 | Requesting a content object by its ID will get you all available data for 78 | that article. Partial field selection is available, if not all fields are 79 | of interest. 80 |

81 | 82 |

Endpoint

83 |

{{ api_url }}/content/{id}

84 | 85 |

Example

86 | 87 |

Request

88 |

GET /content/1111122299xxcc99aa HTTP/1.1
 89 | Host: {{ api_url }}
 90 | X-Authorization: abcdefg1234xyz56789
 91 |

92 | 93 |

Response

94 |

{
 95 |     "title": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
 96 |     "release_date": "2011-12-01T14:40:00.000Z", 
 97 |     "uri": "{{ api_url }}/content/1111122299xxcc99aa",
 98 |     "supertitle": "Lorem Ipsum", 
 99 |     "href": "http://www.zeit.de/lorem/ipsum/2012-12/Lorem-ipsum-dolor-sit-que",
100 |     "teaser_text": "Stet clita kasd gubergren, no sea takimata sanctus est
101 |         Lorem ipsum dolor sit amet."
102 |     "teaser_title": "Lorem ipsum dolor sit amet, consetetur sadipscing.",
103 |     "creators": [
104 |         {
105 |             "uri": "{{ api_url }}/author/James-Mustermann",
106 |             "rel": "author",
107 |             "name": "James Mustermann"
108 |         }
109 |     ],
110 |     "relations": [
111 |         {
112 |             "uri": "{{ api_url }}/content/55555ccc333aaawww",
113 |             "rel": "related",
114 |             "name": "Eirmod tempor invidunt ut labore"
115 |         },
116 |         {
117 |             "uri": "{{ api_url }}/content/333322ssssQQQrrrr",
118 |             "rel": "related",
119 |             "name": "No sea takimata sanctus est"
120 |         }
121 |     ],
122 |     "keywords": [
123 |         {
124 |             "uri": "{{ api_url }}/keyword/lorem",
125 |             "rel": "location",
126 |             "name": "Lorem"
127 |         },
128 |         {
129 |             "uri": "{{ api_url }}/keyword/ipsum-set",
130 |             "rel": "subject",
131 |             "name": "Ipsum Set"
132 |         }
133 |     ],
134 |     "categories": [
135 |         {
136 |             "uri": "{{ api_url }}/department/lorem",
137 |             "rel": "department",
138 |             "name": "Lorem"
139 |         },
140 |         {
141 |             "uri": "{{ api_url }}/product/dolores",
142 |             "rel": "product",
143 |             "name": "Dolores"
144 |         },
145 |         {
146 |             "uri": "{{ api_url }}/department/ipsum",
147 |             "rel": "sub_department",
148 |             "name": "Ipsum"
149 |         }
150 |     ]
151 | }

152 | 153 | {% endblock %} 154 | -------------------------------------------------------------------------------- /src/zeit/api/templates/explorer.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}API Explorer{% endblock %} 3 | {% block docBody %} 4 | 5 |

6 | You can browse the API with this interactive explorer. Select an endpoint 7 | to see its available parameters and their default values. If you have 8 | requested an API key, it is 9 | inserted automatically in the form below. 10 |

11 | 12 |

Request

13 |

 14 | GET /
 15 | 
Host: {{ api_url }}
 16 | X-Authorization: 
 17 |

18 |

Send request

19 |

Response

20 |

 21 | 
 22 |

23 | 24 | 164 | 165 | {% endblock %} 166 | -------------------------------------------------------------------------------- /src/zeit/api/templates/quickstart.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Quick Start Guide{% endblock %} 3 | {% block docBody %} 4 | 5 |

Request an API key

6 | 7 |

Accessing our content requires an API key. To request one, simply 8 | sign up with your full name and a valid Email address. A key will be 9 | generated for you right here on this page. At the moment we offer free 10 | API-Access with a limit of 10,000 requests per day.

11 | 12 |

Sign up

13 | 14 | 16 | 17 |

18 | 19 | 20 | 24 | 28 | 29 | 30 | 31 | 39 | 40 |

21 \| 23 \|	25 \| 26 \| 27 \|
	32 \| 33 \| 34 \| I have read and accept the 35 \| licence agreement. 36 \| 37 \| Request API key 38 \|

41 |

42 |

43 |

44 | 45 | 122 | 123 |

124 |

Authorize requests

125 | 126 |

127 | All requests to our API must be authorized, so we know who plays with our 128 | data. To keep URLs simple and clean, the key should be sent as an 129 | X-Authorization header attached to your HTTP request. 130 |

131 | 132 |

Example

133 |

GET /{endpoint} HTTP/1.1
134 | Host: {{ api_url }}
135 | X-Authorization: {api_key}
136 |

137 | 138 |

139 | The key may also be sent as a query parameter, but a header is preferred. 140 |

141 | 142 |

Example

143 |

GET /{endpoint}?api_key={api_key} HTTP/1.1
144 | Host: {{ api_url }}
145 |

146 | 147 |

148 |

Available formats

149 |

150 | The supported content types for now are JSON and 152 | JSONP, simple as that. The default is JSON.
To get JSONP, a 153 | callback parameter specifying the function's name is required. 154 |

155 | 156 |

Example

157 |

GET /{endpoint}?callback=myCallbackName HTTP/1.1
158 | Response: myCallbackName({"result":"data"});

159 | 160 |

161 |

Error handling

162 |

If there was something wrong with your request or, if for some reason, we 163 | dropped the ball, you will receive an appropriate HTTP status code. The 164 | body will contain a JSON-encoded description of what might have been the 165 | problem. 166 |

167 | 168 |

Example

169 |

HTTP/1.0 401 UNAUTHORIZED
170 | Content: {"description": "The provided API key seems to be invalid."}
171 |

172 | 173 |

174 | 175 |

Start exploring

176 |

177 | Now, that you have learned the basics, head over to our API Explorer or digg into the 179 | documentation. 180 |

181 | 182 | {% endblock %} 183 | -------------------------------------------------------------------------------- /src/zeit/api/blueprints.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.blueprints 4 | ~~~~~~~~~~~~~~~~~~~ 5 | 6 | This module configures two blueprint instances, one for the api server and 7 | one for the developer portal and documentation. 8 | 9 | Copyright: (c) 2013 by ZEIT ONLINE. 10 | License: BSD, see LICENSE.md for more details. 11 | """ 12 | import contextlib 13 | import sqlite3 14 | 15 | import flask 16 | from flask import g, jsonify, current_app as current_app 17 | from werkzeug.datastructures import ImmutableDict 18 | 19 | from . import access, metadata, exception, queries 20 | 21 | 22 | api_server = flask.Blueprint('api_server', __name__) 23 | developer_portal = flask.Blueprint('developer_portal', __name__) 24 | developer_portal.jinja_options = ImmutableDict( 25 | {'extensions': ['jinja2.ext.loopcontrols']}) 26 | 27 | 28 | @api_server.app_errorhandler(400) 29 | def handle_bad_request(error): 30 | return exception.bad_request(error) 31 | 32 | 33 | @api_server.app_errorhandler(404) 34 | def handle_resource_not_found(error): 35 | return exception.resource_not_found(error) 36 | 37 | 38 | @api_server.app_errorhandler(405) 39 | def handle_method_not_allowed(error): 40 | return exception.method_not_allowed(error) 41 | 42 | 43 | @api_server.app_errorhandler(500) 44 | def handle_internal_server_error(error): 45 | return exception.internal_server_error(error) 46 | 47 | 48 | @api_server.before_app_first_request 49 | def initialize_database(): 50 | """On first startup, make sure the database is initialized.""" 51 | g.db = sqlite3.connect(current_app.config['DATABASE'], 52 | isolation_level=None) 53 | schema = (current_app.root_path + current_app.config['SCHEMA']) 54 | with contextlib.closing(g.db) as db: 55 | with api_server.open_resource(schema) as f: 56 | db.cursor().executescript(f.read()) 57 | db.commit() 58 | 59 | 60 | @api_server.before_app_request 61 | def before_request(): 62 | """Intercept preflight requests, connect db and extract API key.""" 63 | if flask.request.method == 'OPTIONS': 64 | return flask.Response(status=204) 65 | g.db = sqlite3.connect(current_app.config['DATABASE'], 66 | isolation_level=None) 67 | g.api_key = flask.request.headers.get('X-Authorization', 68 | flask.request.args.get('api_key', None)) 69 | 70 | 71 | @api_server.after_app_request 72 | def after_request(response): 73 | """Optionally convert to JSONP, set response headers and close db.""" 74 | callback = flask.request.args.get('callback', False) 75 | if callback: 76 | response.data = str(callback) + '(' + response.data + ');' 77 | response.mimetype = 'application/javascript' 78 | response.mimetype += ';charset=UTF-8' 79 | response.headers['Server'] = 'Zeit Api' 80 | response.headers['Cache-Control'] = 'max-age=1' 81 | if hasattr(g, 'db'): 82 | g.db.close() 83 | return response 84 | 85 | 86 | @api_server.route('/') 87 | def show_definition(): 88 | query = queries.DefinitionQuery() 89 | return jsonify(query.fetch()) 90 | 91 | 92 | @api_server.route('/trigger') 93 | def trigger_update(): 94 | metadata.update() 95 | return flask.Response(status=204) 96 | 97 | 98 | @api_server.route('/client', methods=['POST']) 99 | def register_client(): 100 | form = flask.request.form.copy().to_dict() 101 | query = queries.RegisterClientQuery(**form) 102 | return jsonify(query.push()) 103 | 104 | 105 | @api_server.route('/') 106 | def search(endpoint): 107 | with access.Verifictaion(): 108 | param = flask.request.args.copy().to_dict() 109 | query = queries.QueryFactory(endpoint, **param) 110 | return jsonify(query.fetch()) 111 | 112 | 113 | @api_server.route('//') 114 | def filtered_search(endpoint, res): 115 | with access.Verifictaion(): 116 | param = flask.request.args.copy().to_dict() 117 | query = queries.FilteredContentSearchQuery(endpoint, res, **param) 118 | return jsonify(query.fetch()) 119 | 120 | 121 | @api_server.route('/content/') 122 | def content_by_id(uuid): 123 | with access.Verifictaion(): 124 | param = flask.request.args.copy().to_dict() 125 | query = queries.ContentIdQuery(uuid, **param) 126 | return jsonify(query.fetch()) 127 | 128 | 129 | @developer_portal.route('/') 130 | def redirect_index(): 131 | return flask.redirect('/index/') 132 | 133 | 134 | @developer_portal.route('/style.css') 135 | def style_sheet(): 136 | response = flask.make_response(flask.render_template('style.css')) 137 | response.headers['Content-Type'] = 'text/css' 138 | return response 139 | 140 | 141 | @developer_portal.route('//') 142 | def documentation(path): 143 | if 'documentation' in path: 144 | return flask.redirect(path.replace('documentation', 'docs')) 145 | 146 | context = dict( 147 | trunk=path if '/' not in path else path.split('/')[0], 148 | file=path if '/' not in path else path.split('/')[-1], 149 | recaptcha=current_app.config['RECAPTCHA_PUBLIC_KEY'], 150 | api_url=current_app.config['API_URL'], 151 | doc_url=current_app.config['DOC_URL'] 152 | ) 153 | try: 154 | return flask.render_template(path + '.html', **context) 155 | except Exception, e: 156 | current_app.logger.error('%r: %s' % (e, e.message)) 157 | rendered = flask.render_template('error.html', **context) 158 | return flask.make_response(rendered, 404) 159 | 160 | 161 | @developer_portal.after_app_request 162 | def caching(response): 163 | response.headers['Cache-Control'] = 'max-age=7200, public' 164 | response.headers['Server'] = 'Zeit Developer' 165 | return response 166 | -------------------------------------------------------------------------------- /src/zeit/api/parameters.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.parameters 4 | ~~~~~~~~~~~~~~~~~~~ 5 | 6 | This module contains classes for various request parameters. 7 | They provide methods for validation and translation to Solr parameter 8 | namespace. 9 | 10 | Copyright: (c) 2013 by ZEIT ONLINE. 11 | License: BSD, see LICENSE.md for more details. 12 | """ 13 | 14 | import re 15 | 16 | from . import exception, util 17 | 18 | 19 | class Param(object): 20 | """The base class for all URL parameters.""" 21 | 22 | key = None 23 | default = None 24 | origin = None 25 | 26 | def __init__(self, **kwargs): 27 | vkeys = list(k for k in kwargs.keys()) 28 | vargs = dict((k, v) for k, v in kwargs.iteritems() if k in vkeys) 29 | self.__dict__.update(vargs) 30 | self._value = None 31 | 32 | @property 33 | def value(self): 34 | return self._value or self.default 35 | 36 | @value.setter 37 | def value(self, value): 38 | try: 39 | self.valid(value) 40 | self._value = value 41 | except AssertionError: 42 | raise exception.JSONBadRequest() 43 | 44 | def __repr__(self): 45 | return str(self.value) 46 | 47 | def valid(self, value): 48 | pass 49 | 50 | 51 | class StrParam(Param): 52 | """The base class for string parameters.""" 53 | 54 | default = '' 55 | 56 | def __init__(self, **kwargs): 57 | super(StrParam, self).__init__(**kwargs) 58 | 59 | def valid(self, value): 60 | super(StrParam, self).valid(value) 61 | assert isinstance(value, basestring) 62 | 63 | 64 | class SqlQParam(StrParam): 65 | """A parameter class enforcing SQL syntax.""" 66 | 67 | default = '%' 68 | key = 'q' 69 | 70 | def __init__(self, **kwargs): 71 | super(SqlQParam, self).__init__(**kwargs) 72 | 73 | def valid(self, value): 74 | super(SqlQParam, self).valid(value) 75 | assert len(value) < 1024 76 | 77 | @property 78 | def value(self): 79 | return self._value or self.default 80 | 81 | @value.setter 82 | def value(self, value): 83 | try: 84 | self.valid(value) 85 | self._value = value.replace('*', '%') 86 | except AssertionError: 87 | raise exception.JSONBadRequest() 88 | 89 | 90 | class FacetFieldParam(StrParam): 91 | """A parameter class for field facetting.""" 92 | 93 | default = '' 94 | origin = 'facet.field' 95 | key = 'facet_field' 96 | 97 | def __init__(self, **kwargs): 98 | super(FacetFieldParam, self).__init__(**kwargs) 99 | 100 | def valid(self, value): 101 | super(FacetFieldParam, self).valid(value) 102 | whitelist = [ 103 | 'department', 104 | 'product', 105 | 'sub_department', 106 | 'keyword', 107 | 'author', 108 | 'series' 109 | ] 110 | assert value in whitelist 111 | 112 | 113 | class FacetDateParam(StrParam): 114 | """A parameter class for date facetting.""" 115 | 116 | default = '' 117 | origin = 'facet.date.gap' 118 | key = 'facet_date' 119 | 120 | def __init__(self, **kwargs): 121 | super(FacetDateParam, self).__init__(**kwargs) 122 | 123 | def valid(self, value): 124 | super(FacetDateParam, self).valid(value) 125 | assert(re.match(r"^[0-9]{1,3}(day|month|year)$", value)) 126 | 127 | @property 128 | def value(self): 129 | return self._value or self.default 130 | 131 | @value.setter 132 | def value(self, value): 133 | try: 134 | self.valid(value) 135 | self._value = util.ensure_prefix(value, '+').upper() 136 | except AssertionError: 137 | raise exception.JSONBadRequest() 138 | 139 | 140 | class IntParam(Param): 141 | """The base class for integer parameters.""" 142 | 143 | default = '0' 144 | 145 | def __init__(self, **kwargs): 146 | super(IntParam, self).__init__(**kwargs) 147 | 148 | def __radd__(self, other): 149 | result = IntParam() 150 | result.value = str(int(self.value) + other) 151 | return result 152 | 153 | def valid(self, value): 154 | super(IntParam, self).valid(value) 155 | assert hasattr(value, 'isdigit') and value.isdigit() 156 | 157 | 158 | class LimitParam(IntParam): 159 | """A class for limit parameters.""" 160 | 161 | default = '10' 162 | origin = 'rows' 163 | key = 'limit' 164 | 165 | def __init__(self, **kwargs): 166 | super(LimitParam, self).__init__(**kwargs) 167 | 168 | def valid(self, value): 169 | super(LimitParam, self).valid(value) 170 | assert int(value) >= 0 and int(value) <= 1024 171 | 172 | 173 | class OffsetParam(IntParam): 174 | """A class for offset parameters.""" 175 | 176 | default = '0' 177 | origin = 'start' 178 | key = 'offset' 179 | 180 | def __init__(self, **kwargs): 181 | super(OffsetParam, self).__init__(**kwargs) 182 | 183 | def valid(self, value): 184 | super(OffsetParam, self).valid(value) 185 | 186 | 187 | class CsvParam(StrParam): 188 | """The base class for comma seperated values.""" 189 | 190 | def __init__(self, **kwargs): 191 | super(CsvParam, self).__init__(**kwargs) 192 | 193 | def __iter__(self): 194 | for item in self.value.split(','): 195 | if item != '' and item in self.default.split(','): 196 | yield item 197 | 198 | def valid(self, value): 199 | super(CsvParam, self).valid(value) 200 | assert all(item in self.default.split(',') for item in self) 201 | 202 | 203 | class FieldsParam(CsvParam): 204 | """A class for parial selection parameters.""" 205 | 206 | key = 'fields' 207 | origin = 'fl' 208 | enforce = '' 209 | 210 | def __init__(self, **kwargs): 211 | super(FieldsParam, self).__init__(**kwargs) 212 | 213 | def valid(self, value): 214 | super(FieldsParam, self).valid(value) 215 | 216 | @property 217 | def value(self): 218 | if not self._value: 219 | return self.default 220 | if self.enforce != '' and self.enforce not in self._value.split(','): 221 | return '%s,%s' % (self.enforce, self._value) 222 | else: 223 | return self._value 224 | 225 | @value.setter 226 | def value(self, value): 227 | try: 228 | self.valid(value) 229 | self._value = value if '*' not in value else self.default 230 | except AssertionError: 231 | raise exception.JSONBadRequest() 232 | -------------------------------------------------------------------------------- /src/zeit/api/templates/docs.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block docTitle %}Documentation{% endblock %} 3 | {% block docBody %} 4 | 5 |

Endpoints

6 | 7 |

8 | The API is structured into several endpoints that provide specific 9 | functionalities: 10 |

11 | 12 | 13 | 14 | 17 | 20 | 23 | 26 | 27 | 28 | 31 | 34 | 35 | 36 | 37 | 38 | 41 | 44 | 47 | 50 | 51 | 52 | 55 | 58 | 61 | 64 | 65 | 66 | 69 | 72 | 75 | 78 | 79 | 80 | 83 | 86 | 89 | 92 | 93 | 94 | 97 | 100 | 103 | 106 | 107 |

15 \| `/author` 16 \|	18 \| search all authors 19 \|	21 \| `/author/{id}` 22 \|	24 \| content by this author 25 \|
29 \| `/client` 30 \|	32 \| observe API usage 33 \|
39 \| `/content` 40 \|	42 \| search for content 43 \|	45 \| `/content/{id}` 46 \|	48 \| get content by ID 49 \|
53 \| `/department` 54 \|	56 \| search all departments 57 \|	59 \| `/department/{id}` 60 \|	62 \| content from this department 63 \|
67 \| `/keyword` 68 \|	70 \| search all keywords 71 \|	73 \| `/keyword/{id}` 74 \|	76 \| content about this keyword 77 \|
81 \| `/product` 82 \|	84 \| search all products 85 \|	87 \| `/product/{id}` 88 \|	90 \| content from this product 91 \|
95 \| `/series` 96 \|	98 \| search all series 99 \|	101 \| `/series/{id}` 102 \|	104 \| content in this series 105 \|

108 | 109 |

110 | 111 |

Search Syntax

112 | 113 |

114 | The q parameter supports simple Solr query syntax for the 115 | /content endpoint and all /{ep}/{id} endpoints. 116 | Here are a few basics to get you started. For more details check out the 117 | 118 | Apache Solr documentation. 119 |

120 |

121 | Full text search: You can search the entire article text and all 122 | meta data simply by setting the query parameter to your search phrase. 123 | John+Fitzgerald+Kennedy will search for multiple tokens and 124 | "John%20Fitzgerald%20Kennedy" will search for the entire 125 | string. 126 |

127 |

128 | Field queries: All fields of an article can be queried individually. 129 | For example, to get articles that have the word "Kennedy" in their headline, 130 | you would search for title:"Kennedy". 131 |

132 |

133 | Boolean operators: To form a boolean expression of multiple queries, 134 | connect them with
an AND or an OR. So if you 135 | want to search the subtitle for "Kennedy" as well, you can modify the query 136 | to
title:"Kennedy" AND subtitle:"Kennedy". 137 |

138 |

139 | Range queries: You can specify a date range for your query using 140 | full ISO 8601 date syntax.
Getting all Kennedy related articles from 141 | the 60s would work like this:
142 | "Kennedy" AND release_date:[1960-01-01T00:00:00Z TO 143 | 1969-12-31T23:59:59.999Z]. 144 |

145 |

146 | Non-content search: All other endpoints currently only support 147 | simple search phrases with asterisk wildcards. So, a search for Kennedy 148 | related keywords goes like this: /keyword?q=*Kennedy 149 |

150 | 151 |

152 | 153 |

Pagination

154 | 155 |

156 | Search results are limited to 10 matches by default. You can increase this 157 | value with the limit parameter. To iterate over the resultset, 158 | repeat your request with the offset parameter set to multiples 159 | of the limit. 160 |

161 | 162 |

163 | 164 |

Partial Selection

165 | 166 |

167 | By default, the API returns all available fields for your request. To speed 168 | things up, you can specify which fields the server should return using the 169 | fields paramter. If the request returns an array of matches, 170 | this setting only affects entries within that array. So, for example the 171 | field found cannot be deselected, as it always resides outside 172 | of the matches array. 173 |

174 | 175 |

176 | 177 |

Sorting

178 | 179 |

180 | Search results, namely those of the /content endpoint, can be 181 | sorted using the sort parameter. Any of the returned fields are 182 | sortable. Direction keywords are asc and desc for 183 | an ascending or descending sort order respectively. Multiple sort orders are 184 | accepted as a comma-separated list, for example: sort=release_date 185 | asc, uuid desc. 186 |

187 | 188 |

189 | 190 |

Facetting

191 | 192 |

193 | The content endpoint also provides a faceting interface. You can display 194 | facets for specific fields and for date ranges. The 195 | facet_field parameter is used to get a frequency distribution 196 | for the different values of a field. The facet_date parameter 197 | returns counts for the distribution over a specified date range. The 198 | facetting results are limited by your search query, but not by pagination 199 | parameters. 200 |

201 |
202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 |

Parameter	Possible values
`facet_field`	`keyword, author, series, department, product` or any combination
`facet_date`	`1day, 7day, 1month, 1year, 10year` or any numerical variation

216 | 217 | {% endblock %} 218 | -------------------------------------------------------------------------------- /src/zeit/api/tests.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.tests 4 | ~~~~~~~~~~~~~~~~ 5 | 6 | This module contains automated testing functionalities. 7 | 8 | Copyright: (c) 2013 by ZEIT ONLINE. 9 | License: BSD, see LICENSE.md for more details. 10 | """ 11 | import json 12 | import random 13 | import unittest 14 | import werkzeug 15 | 16 | from . import application 17 | 18 | 19 | class ClientTestCase(unittest.TestCase): 20 | 21 | def setUp(self): 22 | self.client = application.test_client_factory() 23 | data = dict( 24 | name='Any Name', 25 | email='mail@provider.tld', 26 | challenge='0123456789', 27 | response='abcdefghij' 28 | ) 29 | resp = self.client.post('/client', data=data) 30 | self.parsed = json.loads(resp.data) 31 | 32 | def test_signup(self): 33 | """Client signup successful.""" 34 | self.assertTrue('api_key' in self.parsed) 35 | 36 | def test_unauthorized(self): 37 | """Unauthorized access blocked.""" 38 | resp = self.client.get('/client') 39 | self.assertEqual(resp.status_code, 401) 40 | 41 | def test_api_key_parameter(self): 42 | """Authorization via URL parameter.""" 43 | query_string = dict(api_key=self.parsed['api_key']) 44 | resp = self.client.get('/client', query_string=query_string) 45 | self.assertEqual(resp.status_code, 200) 46 | 47 | def test_x_authorization_header(self): 48 | """Authorization via HTTP header.""" 49 | headers = werkzeug.datastructures.Headers() 50 | headers.add('X-Authorization', self.parsed['api_key']) 51 | resp = self.client.get('/client', headers=headers) 52 | self.assertEqual(resp.status_code, 200) 53 | 54 | 55 | class QueryTestCase(unittest.TestCase): 56 | 57 | def setUp(self): 58 | self.client = application.test_client_factory() 59 | data = dict(name='Some Name', email='mail@provider.tld') 60 | resp = self.client.post('/client', data=data) 61 | self.headers = werkzeug.datastructures.Headers() 62 | self.headers.add('X-Authorization', json.loads(resp.data)['api_key']) 63 | 64 | def __get_json(self, url, data={}): 65 | print 'Checking ' + url + ' with ' + str(data) 66 | resp = self.client.get(url, headers=self.headers) 67 | self.assertEqual(resp.status_code, 200) 68 | return json.loads(resp.data) 69 | 70 | def test_endpoint_availability(self): 71 | """All endpoints up and running.""" 72 | endpoints = self.__get_json('/') 73 | for path in endpoints: 74 | if '{id}' in path: 75 | continue 76 | endpoint = self.__get_json('/' + path) 77 | if 'matches' in endpoint: 78 | for match in endpoint['matches']: 79 | ids = (match[i] for i in ['id', 'uuid'] if i in match) 80 | for i in list(ids): 81 | self.__get_json('/' + path + '/' + i) 82 | 83 | def test_parameter_defaults(self): 84 | """Parameters accepting their default values.""" 85 | for endpoint, definition in self.__get_json('/').items(): 86 | if '{id}' in endpoint: 87 | continue 88 | for param, val in definition['params'].items(): 89 | self.__get_json('/' + endpoint, {param: val}) 90 | 91 | 92 | class ParameterTestCase(unittest.TestCase): 93 | 94 | def setUp(self): 95 | self.client = application.test_client_factory() 96 | data = dict(name='Some Name', email='mail@provider.tld') 97 | resp = self.client.post('/client', data=data) 98 | self.headers = werkzeug.datastructures.Headers() 99 | self.headers.add('X-Authorization', json.loads(resp.data)['api_key']) 100 | resp = self.client.get('/', headers=self.headers) 101 | self.endpoints = json.loads(resp.data) 102 | 103 | def test_callback_parameter(self): 104 | """Callback parameter results in JSONP output.""" 105 | for ep in self.endpoints: 106 | if '{id}' in ep or 'client' in ep: 107 | continue 108 | rnd = ''.join(random.choice('abcdefghij') for x in range(5)) 109 | json_resp = self.client.get( 110 | '/' + ep, 111 | query_string=dict(limit=1), 112 | headers=self.headers 113 | ) 114 | jsonp_resp = self.client.get( 115 | '/' + ep, 116 | query_string=dict(callback=rnd, limit=1), 117 | headers=self.headers 118 | ) 119 | expected = rnd + '(' + json_resp.data + ');' 120 | self.assertEqual(expected, jsonp_resp.data) 121 | 122 | def test_limit_parameter(self): 123 | """Limit parameter behaves as expected.""" 124 | for ep in self.endpoints: 125 | if '{id}' in ep or 'limit' not in self.endpoints[ep]['params']: 126 | continue 127 | for entry, result in [(-1, 0), (0, 0), (1, 1), (1025, 0)]: 128 | resp = self.client.get( 129 | '/' + ep, 130 | query_string=dict(limit=entry), 131 | headers=self.headers 132 | ) 133 | matches = json.loads(resp.data).get('matches', []) 134 | self.assertEqual(len(matches), result) 135 | 136 | def test_offset_parameter(self): 137 | """Offset parameter behaves as expected.""" 138 | for ep in self.endpoints: 139 | if '{id}' in ep or 'offset' not in self.endpoints[ep]['params']: 140 | continue 141 | resp = self.client.get( 142 | '/' + ep, 143 | query_string=dict(limit=0), 144 | headers=self.headers 145 | ) 146 | maximum = json.loads(resp.data)['found'] 147 | 148 | for entry, code in [(-1, 400), (0, 200), (maximum, 200)]: 149 | resp = self.client.get( 150 | '/' + ep, 151 | query_string=dict(offset=entry), 152 | headers=self.headers 153 | ) 154 | self.assertEqual(resp.status_code, code) 155 | 156 | def test_fields_parameter(self): 157 | """Fields parameter behaves as expected.""" 158 | for ep in self.endpoints: 159 | if '{id}' in ep or 'fields' not in self.endpoints[ep]['params']: 160 | continue 161 | fields = self.endpoints[ep]['params']['fields'].split(',') 162 | 163 | for n in range(1, len(fields)): 164 | for perm_fields in [fields[:n]]: 165 | query_string = dict( 166 | fields=','.join(perm_fields), 167 | limit=1 168 | ) 169 | resp = self.client.get( 170 | '/' + ep, 171 | query_string=query_string, 172 | headers=self.headers 173 | ) 174 | print 'Checking /' + ep + ' with ' + str(query_string) 175 | parsed_fields = json.loads(resp.data)['matches'][0].keys() 176 | sd = set(perm_fields).symmetric_difference(set(parsed_fields)) 177 | self.assertTrue(sd.issubset(['snippet'])) 178 | 179 | 180 | if __name__ == '__main__': 181 | unittest.main() 182 | -------------------------------------------------------------------------------- /src/zeit/api/templates/style.css: -------------------------------------------------------------------------------- 1 | #header h1.cap:after { 2 | content: 'beta'; 3 | vertical-align: top; 4 | font-size: 50%; 5 | padding-left: 3px; 6 | } 7 | 8 | #main { 9 | width: 750px; 10 | } 11 | 12 | #main p { 13 | font-family: Georgia, Palatino, Palatino Linotype, FreeSerif, serif; 14 | line-height: 1.3em; 15 | } 16 | 17 | #informatives { 18 | padding: 0 1em; 19 | width: 160px; 20 | } 21 | 22 | #informatives ul { 23 | width: auto; 24 | margin: .75em 0 1.5em; 25 | } 26 | 27 | #informatives .sidenav { 28 | list-style-type: none; 29 | } 30 | 31 | #informatives .sidenav .indent { 32 | list-style-type: square; 33 | list-style-position:inside; 34 | } 35 | 36 | #informatives .sidenav.current a, 37 | #informatives ul .current a { 38 | color: #444; 39 | text-decoration: underline; 40 | } 41 | 42 | #informatives ul.sidenav a { 43 | font-weight: 600; 44 | text-transform: uppercase; 45 | } 46 | 47 | #informatives ul.sidenav a:hover { 48 | color: #444; 49 | } 50 | 51 | #informatives #sidenavHeader { 52 | font-size: 17px; 53 | font-weight: 600; 54 | margin-bottom: 10px; 55 | } 56 | 57 | #informatives .sidenavLink { 58 | margin: 0 0 5px -10px; 59 | } 60 | 61 | #informatives a.sidenavBlogLink { 62 | border: 1px solid #ccc; 63 | padding: 3px 6px 3px 38px; 64 | border-radius: 3px; 65 | font-size: 10px; 66 | font-weight: 600; 67 | color: #444; 68 | background: #fafafa url(http://wordpress.org/favicon.ico) no-repeat 2px 0; 69 | } 70 | 71 | #informatives .twitter-follow-button { 72 | margin: 11px 0 0 -10px; 73 | } 74 | 75 | #informatives a.sidenavBlogLink:hover { 76 | background-color: #efefef; 77 | } 78 | 79 | #content.section { 80 | padding: 0 10px 10px; 81 | margin-bottom: 10px; 82 | min-height: 350px; 83 | background: transparent url(https://static.zeit.de/static/img/bg_content_eee.gif) repeat-y 782px 0px; 84 | } 85 | 86 | #main h1 { 87 | font-size: 1.6em; 88 | margin: 10px 0 20px; 89 | } 90 | 91 | #main h2 { 92 | font-size: 1.2em; 93 | } 94 | 95 | #main h3 { 96 | color: #900; 97 | font-size: 0.6em; 98 | text-transform: uppercase; 99 | margin: 14px 0 10px; 100 | } 101 | 102 | #main h2, #main p, #main code{ 103 | margin: 10px 0; 104 | } 105 | 106 | #signUpWrapper input, #send, select { 107 | border: 1px solid #ccc; 108 | padding: 3px 6px; 109 | border-radius: 3px; 110 | } 111 | 112 | #main .alignCenter { 113 | text-align: center; 114 | } 115 | 116 | #main input:focus:invalid { 117 | border-color: #900; 118 | } 119 | 120 | #main input:required:valid { 121 | border-color: #3CB371; 122 | } 123 | 124 | #main #send { 125 | cursor: pointer; 126 | font-size: 0.8em; 127 | } 128 | 129 | #main select { 130 | cursor: pointer; 131 | } 132 | 133 | #main #signUpWrapper { 134 | position: relative; 135 | } 136 | 137 | #main #signUpWrapper table, #main #signUpWrapper td { 138 | border: none; 139 | } 140 | 141 | #main #signUpWrapper td { 142 | width: 50%; 143 | text-align: center; 144 | } 145 | 146 | #main #signUpWrapper #signUpForm input[name="name"], 147 | #main #signUpWrapper #signUpForm input[name="email"] { 148 | width: 288px; 149 | } 150 | 151 | #main #signUpWrapper #signUpForm input[name="email"] { 152 | margin-top: 5px; 153 | } 154 | 155 | #main #signUpWrapper #signUpError { 156 | position: absolute; 157 | display: none; 158 | top: 10px; 159 | } 160 | 161 | #main #signUpWrapper #signUpForm #send:hover { 162 | border-color: #bbb; 163 | background-color: #e9e9e9; 164 | } 165 | 166 | #main #signUpWrapper #signUpAgreement { 167 | font-size: 11px; 168 | width: 120px; 169 | display: inline-block; 170 | vertical-align: -5px; 171 | } 172 | 173 | .explorerWrapper { 174 | min-height: 70px; 175 | margin-bottom: 20px; 176 | } 177 | 178 | #main pre, #signUpWrapper { 179 | border: 1px solid #ccc; 180 | background-color: #fafafa; 181 | overflow: auto; 182 | padding: 5px 10px; 183 | border-radius: 3px; 184 | } 185 | 186 | #main hr { 187 | border: none; 188 | border-top: 1px solid #eaeaea; 189 | margin: 24px 0; 190 | } 191 | 192 | .explorerWrapper hr { 193 | margin: 12px 0; 194 | } 195 | 196 | #main code, #explorerXAuth, #explorerEndpoint, 197 | #explorerParamWrapper input, #explorerEndpointId { 198 | font-family: Consolas, 'Liberation Mono', Courier, monospace; 199 | font-size: 1em; 200 | line-height: 1.125em; 201 | } 202 | 203 | #main p code { 204 | background-color: #fafafa; 205 | outline: 1px solid #ccc; 206 | } 207 | 208 | #explorerStatus hr { 209 | margin: 10px 0; 210 | } 211 | 212 | #explorerEndpoint { 213 | width: 100px; 214 | } 215 | 216 | .explorerZonLink { 217 | color: #004c99 !important; 218 | } 219 | 220 | #explorerParamWrapper { 221 | position: relative; 222 | margin: -18px 0px 6px; 223 | min-height: 1.2em; 224 | width: 595px; 225 | left: 140px; 226 | } 227 | 228 | #explorerParamWrapper span:first-child:before { 229 | content: '?'; 230 | } 231 | 232 | #explorerParamWrapper span:before { 233 | content: '&'; 234 | } 235 | 236 | #explorerParamWrapper span:after { 237 | content: '='; 238 | } 239 | 240 | #explorerParamWrapper input { 241 | width: 400px; 242 | } 243 | 244 | #explorerEndpoint, #explorerXAuth, 245 | #explorerParamWrapper input, 246 | #explorerEndpointId { 247 | margin: 0px; 248 | padding: 0px; 249 | border: none; 250 | border-width: 0px; 251 | background: #fafafa; 252 | color: #222; 253 | appearance: textfield; 254 | -moz-appearance: textfield; 255 | -webkit-appearance: textfield; 256 | } 257 | 258 | #explorerParamWrapper input { 259 | color: #777;; 260 | } 261 | 262 | #explorerEndpointSpan { 263 | margin-left: 4px; 264 | } 265 | 266 | #main table { 267 | background-color: #fafafa; 268 | border-spacing: 0px; 269 | width: 100%; 270 | } 271 | 272 | #main table td { 273 | border: 1px solid #ccc; 274 | padding: 5px 10px; 275 | border-right-width: 0px; 276 | border-bottom-width: 0px; 277 | } 278 | 279 | #main table tr:last-child td:first-child { 280 | -moz-border-radius-bottomleft: 3px; 281 | -webkit-border-bottom-left-radius: 3px; 282 | border-bottom-left-radius: 3px; 283 | } 284 | 285 | #main table tr:last-child td:last-child { 286 | -moz-border-radius-bottomright: 3px; 287 | -webkit-border-bottom-right-radius: 3px; 288 | border-bottom-right-radius: 3px; 289 | } 290 | 291 | #main table tr:first-child td:first-child { 292 | -moz-border-radius-topleft: 3px; 293 | -webkit-border-top-left-radius: 3px; 294 | border-top-left-radius: 3px; 295 | } 296 | 297 | #main table tr:first-child td:last-child { 298 | -moz-border-radius-topright: 3px; 299 | -webkit-border-top-right-radius: 3px; 300 | border-top-right-radius: 3px; 301 | } 302 | 303 | #main table tr td:last-child { 304 | border-right-width: 1px; 305 | } 306 | 307 | #main table tr:last-child td { 308 | border-bottom-width: 1px; 309 | } 310 | 311 | #main table td span.default { 312 | color: #aaa; 313 | -moz-user-select: -moz-none; 314 | -khtml-user-select: none; 315 | -webkit-user-select: none; 316 | -ms-user-select: none; 317 | user-select: none; 318 | } 319 | 320 | #main table td span.default:before { 321 | content: '='; 322 | padding-left: 3px; 323 | } 324 | 325 | #main .floatColumn { 326 | float: left; 327 | width: 360px; 328 | text-align: justify;; 329 | } 330 | 331 | #main .floatColumn.leftColumn { 332 | padding-right: 20px; 333 | } 334 | 335 | #main #indexImg { 336 | background-image: url(https://img.zeit.de/administratives/header.jpg); 337 | background-size: cover; 338 | width: 740px; 339 | height: 250px; 340 | } 341 | 342 | #main .indexImgCredit { 343 | color: #555; 344 | font-size: 0.8em; 345 | float: right; 346 | margin: 228px 0 0 0; 347 | background: #fff; 348 | padding: 3px; 349 | } 350 | -------------------------------------------------------------------------------- /src/zeit/api/queries.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | zeit.api.queries 4 | ~~~~~~~~~~~~~~~~ 5 | 6 | This module contains classes for the different kind of queries a client 7 | may submit to the API. These define allowed parameters and values, methods 8 | to fetch a raw result set from a Solr server and transform or enrich the 9 | received results. 10 | 11 | Copyright: (c) 2013 by ZEIT ONLINE. 12 | License: BSD, see LICENSE.md for more details. 13 | """ 14 | 15 | import json 16 | import exceptions 17 | import os 18 | import time 19 | import urllib 20 | import urllib2 21 | import warnings 22 | 23 | from flask import g, current_app as current_app, request 24 | 25 | from . import exception, parameters, util 26 | 27 | 28 | class Query(object): 29 | """The base class for all API queries.""" 30 | 31 | def __getitem__(self, key): 32 | if key not in self.__dict__.keys(): 33 | raise exceptions.KeyError() 34 | return self.__dict__[key] 35 | 36 | def __init__(self, **kwargs): 37 | for kw in kwargs: 38 | if kw in self.__dict__.keys(): 39 | getattr(self, kw).value = kwargs[kw] 40 | elif kw == 'callback' or kw == 'api_key': 41 | pass 42 | else: 43 | warnings.warn('Unsupported parameter key %s' % kw) 44 | 45 | def __iter__(self): 46 | for param in self.__dict__.values(): 47 | if isinstance(param, parameters.Param): 48 | yield (param.origin or param.key, param.value) 49 | 50 | def __str__(self): 51 | return str(dict(self.__iter__())) 52 | 53 | def items(self): 54 | return list(self.__iter__()) 55 | 56 | def params(self): 57 | for param in self.__dict__.values(): 58 | if isinstance(param, parameters.Param) and param.key: 59 | yield (param.key, param.value) 60 | 61 | 62 | class SearchQuery(Query): 63 | """The base class for all SQL-based searches.""" 64 | 65 | _default_field = 'value' 66 | 67 | def __init__(self, endpoint, **kwargs): 68 | self.q = parameters.SqlQParam() 69 | self.limit = parameters.LimitParam() 70 | self.offset = parameters.OffsetParam() 71 | self._endpoint = endpoint 72 | super(SearchQuery, self).__init__(**kwargs) 73 | 74 | def _fetch_raw(self): 75 | sql = 'SELECT * FROM %s WHERE %s LIKE ? LIMIT ?, ?;' 76 | query = sql % (self._endpoint, self._default_field) 77 | options = (self.q.value, self.offset.value, self.limit.value) 78 | result = g.db.execute(query, options).fetchall() 79 | return result 80 | 81 | def _fetch_count(self): 82 | sql = 'SELECT COUNT(*) FROM %s WHERE %s LIKE ?;' 83 | query = sql % (self._endpoint, self._default_field) 84 | result = g.db.execute(query, (self.q.value,)).fetchone() 85 | return result[0] 86 | 87 | def _matches(self): 88 | for row in self._fetch_raw(): 89 | match = dict() 90 | for key in self.fields: 91 | position = self.fields.default.split(',').index(key) 92 | match[key] = row[position] 93 | yield match 94 | 95 | def fetch(self): 96 | return dict( 97 | matches=list(self._matches()), 98 | found=self._fetch_count(), 99 | limit=int(self.limit.value), 100 | offset=int(self.offset.value) 101 | ) 102 | 103 | 104 | class AuthorSearchQuery(SearchQuery): 105 | """Search query for content authors.""" 106 | 107 | def __init__(self, **kwargs): 108 | self.fields = parameters.FieldsParam( 109 | default='href,id,type,uri,value' 110 | ) 111 | super(AuthorSearchQuery, self).__init__('author', **kwargs) 112 | 113 | 114 | class DepartmentSearchQuery(SearchQuery): 115 | """Search query for newspaper departments.""" 116 | 117 | def __init__(self, **kwargs): 118 | self.fields = parameters.FieldsParam( 119 | default='href,id,parent,uri,value' 120 | ) 121 | super(DepartmentSearchQuery, self).__init__('department', **kwargs) 122 | 123 | 124 | class KeywordSearchQuery(SearchQuery): 125 | """Search query for available keywords.""" 126 | 127 | def __init__(self, **kwargs): 128 | self.fields = parameters.FieldsParam( 129 | default='href,id,lexical,score,type,uri,value' 130 | ) 131 | super(KeywordSearchQuery, self).__init__('keyword', **kwargs) 132 | 133 | 134 | class ProductSearchQuery(SearchQuery): 135 | """Search query for publication products.""" 136 | 137 | def __init__(self, **kwargs): 138 | self.fields = parameters.FieldsParam( 139 | default='href,id,uri,value' 140 | ) 141 | super(ProductSearchQuery, self).__init__('product', **kwargs) 142 | 143 | 144 | class SeriesSearchQuery(SearchQuery): 145 | """Search query for article series.""" 146 | 147 | def __init__(self, **kwargs): 148 | self.fields = parameters.FieldsParam( 149 | default='href,id,name,uri,value' 150 | ) 151 | super(SeriesSearchQuery, self).__init__('series', **kwargs) 152 | 153 | 154 | class ContentSearchQuery(Query): 155 | """Unfiltered content search query.""" 156 | 157 | _endpoint = 'content' 158 | __action = 'search' 159 | 160 | def __init__(self, **kwargs): 161 | self.q = parameters.StrParam( 162 | key='q', 163 | origin='q', 164 | default='*:*' 165 | ) 166 | self.sort = parameters.StrParam( 167 | key='sort', 168 | origin='sort', 169 | default='release_date desc' 170 | ) 171 | self.fields = parameters.FieldsParam( 172 | default=('subtitle,uuid,title,href,release_date,' 173 | 'uri,snippet,supertitle,teaser_title,teaser_text'), 174 | enforce='uuid' 175 | ) 176 | self.facet_date = parameters.FacetDateParam() 177 | self.facet_field = parameters.FacetFieldParam() 178 | self.limit = parameters.LimitParam() 179 | self.offset = parameters.OffsetParam() 180 | super(ContentSearchQuery, self).__init__(**kwargs) 181 | if self.facet_field.value != '' or self.facet_date.value != '': 182 | self.facet = parameters.StrParam( 183 | key='facet', 184 | origin='facet', 185 | default='true' 186 | ) 187 | if self.facet_date.value != '': 188 | self.facet_date_field = parameters.StrParam( 189 | origin='facet.date', 190 | default='release_date' 191 | ) 192 | 193 | def _fetch_raw(self): 194 | query = util.url_encode(dict(self)) 195 | url = '%s/%s/%s?%s' % (current_app.config['SOLR_URL'], 196 | self.__class__._endpoint, self.__action, query) 197 | try: 198 | data = urllib2.urlopen(url) 199 | return json.load(data) 200 | except urllib2.URLError: 201 | raise exception.service_unavailable() 202 | 203 | def _make_matches(self, raw): 204 | for match in raw['response']['docs']: 205 | if 'uri' in self.fields: 206 | match['uri'] = '%s/%s/%s' % (current_app.config['API_URL'], 207 | self.__class__._endpoint, match['uuid']) 208 | if 'snippet' in self.fields and self.q.value != self.q.default: 209 | snippet = raw['highlighting'][match['uuid']] 210 | if len(snippet.values()) > 0: 211 | match['snippet'] = snippet.values()[0][0] 212 | if self.fields._value: 213 | if 'uuid' not in self.fields._value: 214 | del match['uuid'] 215 | 216 | def fetch(self): 217 | raw = self._fetch_raw() 218 | self._make_matches(raw) 219 | response = dict( 220 | matches=raw['response']['docs'], 221 | found=raw['response']['numFound'], 222 | limit=int(self.limit.value), 223 | offset=int(self.offset.value) 224 | ) 225 | if hasattr(self, 'facet'): 226 | response['facets'] = dict() 227 | response['facets'].update( 228 | raw['facet_counts']['facet_dates']) 229 | response['facets'].update( 230 | raw['facet_counts']['facet_fields']) 231 | return response 232 | 233 | 234 | class FilteredContentSearchQuery(ContentSearchQuery): 235 | """Pre-filtered search query.""" 236 | 237 | _default_field = 'id' 238 | 239 | def __init__(self, endpoint='', filter_id='', **kwargs): 240 | 241 | self.fq = parameters.StrParam( 242 | default='%s:%s' % (endpoint, filter_id), 243 | origin='fq' 244 | ) 245 | super(FilteredContentSearchQuery, self).__init__(**kwargs) 246 | self._endpoint = endpoint 247 | self._id = filter_id 248 | 249 | def fetch(self): 250 | sql = 'SELECT * FROM %s WHERE %s LIKE :q;' 251 | query = sql % (self._endpoint, self._default_field) 252 | result = g.db.execute(query, {'q': self._id}).fetchall() 253 | if len(result) == 0: 254 | raise exception.resource_not_found() 255 | if self._endpoint == 'author': 256 | self.fq.value = self.fq.value.replace('-', '*') 257 | meta = dict(zip(QueryFactory(self._endpoint).fields, result[0])) 258 | if self._endpoint == 'department': 259 | if meta['parent'] != '': 260 | self.fq.value = 'sub_department:%s' % (self._id) 261 | meta.update(super(FilteredContentSearchQuery, self).fetch()) 262 | return meta 263 | 264 | 265 | class DisplayClientQuery(Query): 266 | """Display client information and API usage stats.""" 267 | 268 | def __init__(self, **kwargs): 269 | super(DisplayClientQuery, self).__init__(**kwargs) 270 | 271 | def fetch(self): 272 | row = g.db.execute('SELECT * FROM client WHERE api_key=?', 273 | (g.api_key,)).fetchone() 274 | return dict( 275 | api_key=row[0], 276 | tier=row[1], 277 | name=row[2], 278 | email=row[3], 279 | requests=row[4], 280 | reset=row[5], 281 | quota=current_app.config['ACCESS_TIERS'][row[1]] 282 | ) 283 | 284 | 285 | class RegisterClientQuery(Query): 286 | """Register a new API client with a POST request.""" 287 | 288 | def __init__(self, **kwargs): 289 | self.name = parameters.StrParam() 290 | self.email = parameters.StrParam() 291 | self.response = parameters.StrParam() 292 | super(RegisterClientQuery, self).__init__(**kwargs) 293 | 294 | def _verify_captcha(self): 295 | if current_app.config['TESTING']: 296 | return True 297 | data = urllib.urlencode( 298 | dict( 299 | secret=current_app.config['RECAPTCHA_PRIVATE_KEY'], 300 | remoteip=request.remote_addr, 301 | response=self.response.value, 302 | ) 303 | ) 304 | url = 'https://www.google.com/recaptcha/api/siteverify' 305 | try: 306 | response = json.load(urllib.urlopen(url, data)) 307 | return response['success'] 308 | except Exception: 309 | return False 310 | 311 | def push(self): 312 | empty = self.name.value == '' or self.email.value == '' 313 | if empty or not self._verify_captcha(): 314 | raise exception.bad_request() 315 | g.api_key = str(os.urandom(26).encode('hex')) 316 | tier = 'free' 317 | name = self.name.value 318 | email = self.email.value 319 | requests = 0 320 | reset = int(time.time()) 321 | query = 'INSERT INTO client VALUES (?, ?, ?, ?, ?, ?)' 322 | g.db.execute(query, (g.api_key, tier, name, email, requests, reset)) 323 | return DisplayClientQuery().fetch() 324 | 325 | 326 | class QueryFactory(object): 327 | """A factory class for general endpoint queries.""" 328 | 329 | def __init__(self, endpoint='', **kwargs): 330 | if endpoint == 'author': 331 | self.__class__ = AuthorSearchQuery 332 | elif endpoint == 'client': 333 | self.__class__ = DisplayClientQuery 334 | elif endpoint == 'content': 335 | self.__class__ = ContentSearchQuery 336 | elif endpoint == 'department': 337 | self.__class__ = DepartmentSearchQuery 338 | elif endpoint == 'keyword': 339 | self.__class__ = KeywordSearchQuery 340 | elif endpoint == 'product': 341 | self.__class__ = ProductSearchQuery 342 | elif endpoint == 'series': 343 | self.__class__ = SeriesSearchQuery 344 | else: 345 | raise exception.endpoint_not_found() 346 | self.__init__(**kwargs) 347 | 348 | 349 | class ContentIdQuery(Query): 350 | """Display content item with the given id.""" 351 | 352 | _endpoint = 'content' 353 | __action = 'id' 354 | 355 | def __init__(self, content_id='', **kwargs): 356 | self.fields = parameters.CsvParam( 357 | default=('categories,creators,href,keywords,relations,release_' 358 | 'date,supertitle,teaser_text,teaser_title,title,uri,uuid'), 359 | key='fields' 360 | ) 361 | self.fq = parameters.StrParam( 362 | default='uuid:%s' % content_id, 363 | origin='fq' 364 | ) 365 | self.q = parameters.StrParam( 366 | origin='q', 367 | default='*:*' 368 | ) 369 | super(ContentIdQuery, self).__init__(**kwargs) 370 | 371 | def _fetch_raw(self): 372 | query = util.url_encode(dict(self)) 373 | url = '%s/%s/%s?%s' % (current_app.config['SOLR_URL'], 374 | self.__class__._endpoint, self.__action, query) 375 | try: 376 | data = urllib2.urlopen(url) 377 | return json.load(data) 378 | except urllib2.URLError: 379 | raise exception.service_unavailable() 380 | 381 | def _fetch_keywords(self, keywords): 382 | for keyword in keywords: 383 | query = 'SELECT type, value FROM keyword WHERE id = ?;' 384 | row = g.db.execute(query, (keyword,)).fetchone() 385 | if row is None: 386 | continue 387 | yield dict( 388 | rel=row[0], 389 | name=row[1], 390 | uri='%s/keyword/%s' % (current_app.config['API_URL'], 391 | keyword) 392 | ) 393 | 394 | def _fetch_relations(self, relations): 395 | for relation in relations: 396 | url = '%s/content/id?q=%s' % (current_app.config['SOLR_URL'], 397 | relation) 398 | solr_data = urllib2.urlopen(url) 399 | try: 400 | parsed = json.load(solr_data) 401 | title = parsed['response']['docs'][0]['title'] 402 | except: 403 | continue 404 | yield dict( 405 | rel='related', 406 | name=title, 407 | uri='%s/content/%s' % (current_app.config['API_URL'], 408 | relation) 409 | ) 410 | 411 | def _fetch_authors(self, authors): 412 | for author in authors: 413 | yield dict( 414 | rel='author', 415 | name=author, 416 | uri='%s/author/%s' % (current_app.config['API_URL'], 417 | author.replace(' ', '-')) 418 | ) 419 | 420 | def _fetch_category(self, endpoint, cat_id, type): 421 | query = 'SELECT value FROM %s WHERE id = "%s";' % (endpoint, cat_id) 422 | row = g.db.execute(query).fetchone() 423 | if row: 424 | yield dict( 425 | rel=type, 426 | name=row[0], 427 | uri='%s/%s/%s' % (current_app.config['API_URL'], 428 | endpoint, cat_id) 429 | ) 430 | 431 | def fetch(self): 432 | raw = self._fetch_raw() 433 | 434 | if len(raw['response']['docs']) == 0: 435 | raise exception.resource_not_found() 436 | else: 437 | doc = raw['response']['docs'][0] 438 | 439 | categories = [('department', 'department'), ('product', 'product'), 440 | ('sub_department', 'department'), ('series', 'series')] 441 | whitelist = ['categories', 'creators', 'keywords', 'relations'] 442 | blacklist = ['body'] 443 | 444 | for key in whitelist: 445 | doc[key] = [] 446 | 447 | for key in blacklist: 448 | if key in doc: 449 | del doc[key] 450 | 451 | if 'uri' in self.fields: 452 | doc['uri'] = '%s/%s/%s' % (current_app.config['API_URL'], 453 | self._endpoint, doc['uuid']) 454 | 455 | if 'keyword' in doc and 'keywords' in self.fields: 456 | kw = self._fetch_keywords(doc['keyword']) 457 | doc['keywords'].extend(kw) 458 | del doc['keyword'] 459 | 460 | if 'related' in doc and 'relations' in self.fields: 461 | rl = self._fetch_relations(doc['related']) 462 | doc['relations'].extend(rl) 463 | del doc['related'] 464 | 465 | if 'author' in doc and 'creators' in self.fields: 466 | au = self._fetch_authors(doc['author']) 467 | doc['creators'].extend(au) 468 | del doc['author'] 469 | 470 | for category, endpoint in categories: 471 | if category in doc and 'categories' in self.fields: 472 | cat_id = doc[category] 473 | cat = self._fetch_category(endpoint, cat_id, category) 474 | doc['categories'].extend(cat) 475 | del doc[category] 476 | 477 | for key in doc.keys(): 478 | if key not in self.fields: 479 | del doc[key] 480 | 481 | return doc 482 | 483 | 484 | class DefinitionQuery(Query): 485 | """Return API meta information for all available queries.""" 486 | 487 | def __init__(self, **kwargs): 488 | super(DefinitionQuery, self).__init__(**kwargs) 489 | 490 | def _make_def(self, endpoint, query_class): 491 | url = '%s/%s' % (current_app.config['API_URL'], endpoint) 492 | params = dict(p for p in query_class().params()) 493 | doc = query_class().__doc__ 494 | return endpoint, dict(url=url, params=params, doc=doc) 495 | 496 | def fetch(self): 497 | endpoints = {'author': AuthorSearchQuery, 498 | 'author/{id}': FilteredContentSearchQuery, 499 | 'client': DisplayClientQuery, 500 | 'content': ContentSearchQuery, 501 | 'content/{id}': ContentIdQuery, 502 | 'department': DepartmentSearchQuery, 503 | 'department/{id}': FilteredContentSearchQuery, 504 | 'keyword': KeywordSearchQuery, 505 | 'keyword/{id}': FilteredContentSearchQuery, 506 | 'product': ProductSearchQuery, 507 | 'product/{id}': FilteredContentSearchQuery, 508 | 'series': SeriesSearchQuery, 509 | 'series/{id}': FilteredContentSearchQuery} 510 | return dict(self._make_def(ep, endpoints[ep]) for ep in endpoints) 511 | -------------------------------------------------------------------------------- /src/zeit/api/schemas/schema_.xml: -------------------------------------------------------------------------------- 1 | 2 | 18 | 19 | 31 | 32 | 33 | 39 | 40 | 41 | 48 | 49 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 80 | 81 | 82 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 121 | 122 | 123 | 134 | 135 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 156 | 157 | 158 | 159 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 202 | 203 | 204 | 207 | 208 | 211 | 212 | 213 | 214 | 225 | 228 | 229 | 230 | 231 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 263 | 264 | 265 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 349 | 350 | 351 | 352 | 353 | 356 | id 357 | 358 | 359 | text 360 | 361 | 362 | 363 | 364 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 393 | 394 | 395 | 396 | -------------------------------------------------------------------------------- /src/zeit/api/templates/base.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | ZEIT ONLINE | Developer 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 40 | 41 | 42 | 43 | 44 | 59 | 60 | 61 | 62 | 63 | 74 | 75 | 76 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 184 |

185 | 186 |

187 |

188 |

189 | 190 |

195 |

196 |

197 | 198 |

203 |

204 |

205 |

206 |

207 | 208 |

209 |

210 | 211 | 212 | 343 |

344 | 345 |

346 | 347 |

{% block docTitle %}{% endblock %}

348 | {% block docBody %}{% endblock %} 349 | 350 |

351 |

352 |

354 | Content API 355 |
357 | Quick Start 358 |
360 | API Explorer 361 |
363 | Licence 364 |
366 | Documentation 367 |
369 | Author 370 |
372 | Client 373 |
375 | Content 376 |
378 | Department 379 |
381 | Keyword 382 |
384 | Product 385 |
387 | Series 388 |

390 | 391 | 397 | 398 |

399 |

400 |

401 | 402 |

403 |

404 | nach oben 405 |

406 |

407 |

ANGEBOTE:
Abo
Shop
Christ & Welt
ZEIT Reisen
ZEIT für die Schule
ZEIT Veranstaltungen

416 |

418 |
VERLAG:
Inserieren
Mediadaten
Presse
Unternehmen
Rechte & Lizenzen

425 |

426 | 450 | 451 | 452 |

453 | 454 | 455 |

456 | 457 | 458 |

480 | 481 |

497 | 498 |

499 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | --------------------------------------------------------------------------------

15 \| `/author` 16 \|	18 \| search all authors 19 \|	21 \| `/author/{id}` 22 \|	24 \| content by this author 25 \|
29 \| `/client` 30 \|	32 \| observe API usage 33 \|
39 \| `/content` 40 \|	42 \| search for content 43 \|	45 \| `/content/{id}` 46 \|	48 \| get content by ID 49 \|
53 \| `/department` 54 \|	56 \| search all departments 57 \|	59 \| `/department/{id}` 60 \|	62 \| content from this department 63 \|
67 \| `/keyword` 68 \|	70 \| search all keywords 71 \|	73 \| `/keyword/{id}` 74 \|	76 \| content about this keyword 77 \|
81 \| `/product` 82 \|	84 \| search all products 85 \|	87 \| `/product/{id}` 88 \|	90 \| content from this product 91 \|
95 \| `/series` 96 \|	98 \| search all series 99 \|	101 \| `/series/{id}` 102 \|	104 \| content in this series 105 \|

q*	the main search query
fieldsuri,value,href	partially select output fields
limit10	limit the amount of matches to return
offset0	offset for the list of matches

q:	the main search query
fields*	partially select output fields
limit10	limit the amount of matches to return
offset0	offset for the list of matches

q*	the main search query
fieldsuri,value	partially select output fields
limit10	limit the amount of matches to return
offset0	offset for the list of matches

q*	main search query with asterisk as wildcard
fieldshref,id,type,uri,value	partially select output fields
limit10	amount of matches to return
offset0	offset for the list of matches

q*	the main search query
fieldsuri,value,parent,href	partially select output fields
limit10	limit the amount of matches to return
offset0	offset for the list of matches

q*	the main search query
26 \| fieldsuri,value,lexical,type,score,href 27 \|	partially select output fields
limit10	limit the amount of matches to return
offset0	offset for the list of matches