Difference between revisions of "ISFDB Design Documentation"

Latest revision as of 21:21, 3 September 2016

Introduction

The topics referred to in this article discuss the overall scope and concepts behind the changes from ISFDB1 to ISFDB2. Articles on the layout of the online database schema, XML data submission formats, and the REST API can be found here.

Requirements

CONOPS - The Concept of Operations document is an IEEE standard (1362-1998) for describing the differences between a current system definition and a proposed one. It is less technical and rigorous than well documented feature or system requirements, which makes it more readable to non-engineers. This is the original ISFDB2 CONOPS written in 2001.
Concept of Operations - An updated but still dated version of the Concept of Operations
Requirements:Author Display - Display requirements for author bibliographies
Requirements:Title Display - Display requirements for title bibliographies
Requirements:Publication Display - Display requirements for publication bibliographies
Requirements:Award Display - Display requirements for award bibliographies.
Requirements:Translations - Support for creating/editing/displaying translations

Database Schema and Interfaces

The ISFDB data resides in a MySQL database. The section below describe the database layout, the XML formats for data submissions, the web API, and the Python SQL API.

Database Schema - This article describes the MySQL tables and their relationships.
Data Submission Formats - XML formats for submitting data requests to the ISFDB.
Web API - A set of ISFDB web services that allow a remote application to make queries about publications and to make remote submissions. The submission capability requires a registered login id, a license key and an authorization by the site's administrator. Details on the API can be found in the article.

Internal APIs (out of date)

Python MySQL API - Documentation of the standard Python MySQL methods. This section is provided for ISFDB developers; it is not an exposed interface.
Python Object Classes - Object-oriented classes available for use by applications.
HTML Variables - Documentation of variables contained within an editing form, which are passed to a submission application.

Examples

Michael J. Cross (who is also a short fiction contributor to the ISFDB) has a prototype website up and running using the MySQL database. It is under development, not complete, and subject to change. Here are the links to the Project Page and the Database Page.

@@ Line 3: / Line 3: @@
 The topics referred to in this article discuss the overall scope and concepts behind the changes from ISFDB1 to ISFDB2. Articles on the layout of the online database schema, XML data submission formats, and the REST API can be found here.
-==Concept of Operations==
-The Concept of Operations document is an IEEE standard (1362-1998) for describing the differences between a current system definition and a proposed one. It is less technical and rigorous than well documented feature or system requirements, which makes it more readable to non-engineers. Many things have changed since version 1.0 of the [http://www.isfdb.org/CONOPS.pdf CONOPS] was written in 2001; these changes are reflected in the new [[Concept of Operations]] documentation.
+==Requirements==
-==Database Schema==
+* [http://www.isfdb.org/CONOPS.pdf CONOPS] - The Concept of Operations document is an IEEE standard (1362-1998) for describing the differences between a current system definition and a proposed one. It is less technical and rigorous than well documented feature or system requirements, which makes it more readable to non-engineers. This is the original ISFDB2 CONOPS written in 2001.
+* [[Concept of Operations]] - An updated but still dated version of the Concept of Operations
+* [[Requirements:Author Display]] - Display requirements for author bibliographies
+* [[Requirements:Title Display]] - Display requirements for title bibliographies
+* [[Requirements:Publication Display]] - Display requirements for publication bibliographies
+* [[Requirements:Award Display]] - Display requirements for award bibliographies.
+* [[Requirements:Translations]] - Support for creating/editing/displaying translations
-The ISFDB data resides in a MySQL database. The data resides in tables which are grouped into four categories: author-related, table-related, publication-related, and global data. The online bibliographic pages are constructed directly from these database tables. Modifications to the database are made by inserting XML-formatted submissions into a special submissions table; they are later integrated by a moderator while has the appropriate privileges.
+==Database Schema and Interfaces==
-Details on table structure and relationships can be found in the [[Database Schema]] article.
+The ISFDB data resides in a MySQL database. The section below describe the database layout, the XML formats for data submissions, the web API, and the Python SQL API.
+* [[Database Schema]] - This article describes the MySQL tables and their relationships.
+* [[Data Submission Formats]] - XML formats for submitting data requests to the ISFDB.
+* [[Web API]] - A set of ISFDB web services that allow a remote application to make queries about publications and to make remote submissions. The submission capability requires a registered login id, a license key and an authorization by the site's administrator. Details on the API can be found in the article.
-==Data Submission XML Formats==
+==Internal APIs (out of date)==
+* [[Python MySQL API]] - Documentation of the standard Python MySQL methods. This section is provided for ISFDB developers; it is not an exposed interface.
-Updates to the database are made by submitting data requests. These requests are XML-based, and follow specific [[Data Submission Formats]]. The requests can either be generated via online editing tools available at the main site, or may generated by offline tools and submitted via the Web Services API.
+* [[Python Object Classes]] - Object-oriented classes available for use by applications.
+* [[HTML Variables]] - Documentation of variables contained within an editing form, which are passed to a submission application.
-==Web Services==
-A simple set of ISFDB web services exist that allow a remote application to make queries about publications and to make remote submissions. The submission capability requires a registered login id and a license key.
-Details on table structure and relationships can be found in the [[Web API]] article.
 ==Examples==
 [[Michael J. Cross]] (who is also a short fiction contributor to the ISFDB) has a prototype website up and running using the MySQL database. It is under development, not complete, and subject to change. Here are the links to the [http://www.michaelcross.me.uk/devarea/ Project Page] and the [http://www.michaelcross.me.uk/isfdb/ Database Page].
-==Display Requirements==
-The following pages are intended to capture the detailed display requirements for each type of bibliographic record:
-* [[Requirements:Author Display]]
-* [[Requirements:Title Display]]
-* [[Requirements:Publication Display]]
-* [[Requirements:Award Display]]