updated faq page

docs/DatasetOps/GET_Dataset.rst

@@ -48,7 +48,7 @@ The UUID of the dataset object.
 
 type
 ^^^^
-A JSON object representing the type of the dataset.  See :doc:`../TypeOps/index` for 
+A JSON object representing the type of the dataset.  See :doc:`../Types/index` for 
 details of the type representation.
 
 shape

docs/DomainOps/GET_Domain.rst

@@ -7,7 +7,7 @@ Description
 This operation retrieves information about the requested domain.
 
 *Note:* If the HDF DNS Server (see DNS) is configured 
-(see: :doc:`../../Installation/dns`), the  
+(see: :doc:`../Installation/DNSSetup`), the  
 operations can specify the domain as part of the URI.  Example:  
 http://tall.data.hdfgroup.org:7253/ 
 returns data about the domain "tall" hosted on data.hdfgroup.org.  

docs/DomainOps/index.rst

@@ -7,7 +7,7 @@ file in the traditional HDF5 library.
 Other than :doc:`PUT_Domain`, every operation of the service explicitly
 includes the domain resource in the *Host* line of the http request.
 
-If the included DNS server is set up (see :doc:`../Installation/dns`), the domain
+If the included DNS server is set up (see :doc:`../Installation/DNSSetup`), the domain
 name can also be used as the endpoint of the request.
 
 *Note:* Currently h5serv does not include any functions for listing or querying which

docs/FAQ/index.rst

@@ -3,4 +3,79 @@ FAQ
 ###################
 
 
-   FAQs go here
+What datatypes are supported?
+-----------------------------
+
+=========================           ============================================    
+Type                                Precisions                                       
+=========================           ============================================    
+Integer                             1, 2, 4 or 8 byte, BE/LE, signed/unsigned
+Float                               4, 8  byte, BE/LE
+Compound                            Arbitrary names and offsets
+Strings (fixed-length)              Any length
+Strings (variable-length)           Any length, ASCII 
+Opaque                              Any length
+Array                               Any supported type
+Enumeration                         Any integer type                           
+References                          Region and object
+=========================           ============================================     
+
+Unsupported types:
+
+=========================           ============================================
+Type                                Status                                 
+=========================           ============================================
+HDF5 VLEN (non-string)              Coming soon!
+HDF5 "time" type
+Opaque                              
+Bitfields                            
+=========================           ============================================
+
+
+Why does h5serv use those long ids?
+------------------------------------
+
+h5serv uses the UUID standard (http://en.wikipedia.org/wiki/Universally_unique_identifier)
+to identify objects (datasets, groups, and committed datatypes) uniquely.  The benefit of
+using UUIDs is that objects can be uniquely identified without requiring any central 
+coordination.
+
+How can I get a dataset (or group) via a pathname?
+--------------------------------------------------
+
+You will need to iterate through the path to get the UUID of each subgroup.
+E.g. suppose the path of interest is "/g1/g1.1" in the domain: "tall.data.hdfgroup.org".
+Perform these actions to get the UUID of the group at /g1/g1.1.
+
+#. ``GET /``  // returns the UUID of the root group
+#. ``GET /groups/<root_uuid>/links/g1``  // returns the UUID of the group at "/g1"
+#. ``GET /groups/<g1_uuid>/links/g1.1``  // returns the UUID of the group at "/g1/g1.1'
+
+How do I guard against an attribute (dataset/group/file) from being deleted by a request?
+-----------------------------------------------------------------------------------------
+Future releases of h5serv will support authorization and permissions to protect content
+that shouldn't be altered.
+
+For now the choices are:
+
+#. Don't expose the h5serv endpoint on a non-trusted network
+#. Make the files readonly
+#. Make periodic backups of all data files
+#. Don't share the domain name with non-trusted sources.  Since h5serv doesn't provide an operation to list all domains on the server, creating a non-trivial domain name (e.g. "mydata_18494") will be relatively secure.
+
+How can I display my data in a nice Web UI?
+-------------------------------------------
+There are many Javascript libraries (e.g. http://d3js.org) that can take the data 
+returned by h5serv to create compelling graphics.  
+
+I have a C or Fortran application that uses HDF5, how can I take advantage of h5serv?
+-------------------------------------------------------------------------------------
+We are planning on creating a hdf5 library plugin that will transparently invoke the 
+REST api.  For now, you can use C-libraries such as libcurl to invoke h5serv requests.
+
+How do I submit a bug report?
+------------------------------
+If you have a Github account, create an issue here: 
+https://github.com/HDFGroup/h5serv/issues.
+
+Alternatively, you send a email to the HDF Group help desk: help@hdfgroup.org.

docs/Hypermedia.rst

@@ -2,4 +2,47 @@
 Hypermedia
 *************************
 
-TBD
+h5serv supports the REST convention of **HATEOAS** or *Hypermedia as the Engine of 
+Application State*.  The idea is (see http://en.wikipedia.org/wiki/HATEOS for a full 
+explanation) is that each response include links to related resources related to 
+the requested resource.
+
+For example, consider the request for a dataset: ``GET /datasets/<id>``.  The response
+will be a JSON representation of the dataset describing it's type, shape, and other
+aspects.  Related resources to the dataset would include:
+
+ * the dataset's attributes
+ * the dataset's value
+ * the dataset collection of the domain
+ * the root group of the domain the dataset is in
+ * the domain resource
+
+So the ``GET /datasets/<id>`` response includes a key ``hrefs`` that contains an
+a JSON array.  Each array element has a key: ``href`` - the related resource, and a key:
+``rel`` that denotes the type of relation.   Example:
+
+.. code-block:: json
+       
+    {
+    "hrefs": [
+        {"href": "http://tall.test.hdfgroup.org/datasets/<id>", "rel": "self"}, 
+        {"href": "http://tall.test.hdfgroup.org/groups/<id>", "rel": "root"}, 
+        {"href": "http://tall.test.hdfgroup.org/datasets/<id>/attributes", "rel": "attributes"}, 
+        {"href": "http://tall.test.hdfgroup.org/datasets/<id>/value", "rel": "data"}, 
+        {"href": "http://tall.test.hdfgroup.org/", "rel": "home"}
+      ] 
+    }
+    
+This enables clients to "explore" the api without detailed knowledge of the API.
+
+This is the list of relations used in h5serv:
+
+ * attributes - the attributes of the resource 
+ * data - the resources data (used for datasets)
+ * database - the collection of all datasets in the domain
+ * groupbase - the collection of all groups in the domain
+ * home - the domain the resource is a member of
+ * owner - the containing object of this resource (e.g. the group an attribute is a member of)
+ * root - the root group of the domain the resource is a member of
+ * self - this resource
+ * typebase - the collection of all committed types in the domain

docs/Installation/DNSSetup.rst

@@ -82,7 +82,7 @@ what DNS server software your network is running.  Your sysadmin should be able
 An Example
 ----------
 As an example of how this would work we can look at the h5serv instance setup by The HDF
-Group.  Entering <http://tall.data.hdfgroup.org:7253/> in your browser will return the JSON
+Group.  Entering http://tall.data.hdfgroup.org:7253/ in your browser will return the JSON
 domain response for tall.h5.  
 
 If we trace the chain of events in displaying this page it

docs/Introduction/index.rst

@@ -2,8 +2,11 @@
 Introduction
 ###################
 
-h5serv is a service that provides a RESTful api for HDF5 data as outlined in this paper: 
-http://www.hdfgroup.org/pubs/papers/RESTful_HDF5.pdf.  The serves extends the HDF5 file 
-paradigm to work across any network that is capable of sending http requests. 
+h5serv is a web service that can be used to send and receive HDF5 data.   
+h5serv uses a REST interface to support CRUD (create, read, update, delete) operations on 
+the full spectrum of HDF5 objects including: groups, links, datasets, attributes, and 
+committed data types.   As a REST-based service a variety of clients can be developed in 
+JavaScript, Python, C, and other common languages.
 
+
 

docs/Tutorials/IPython_samples.rst

@@ -1,4 +1,4 @@
 ###################
 Samples 
 ###################
-Some walkthroughs here.
+TBD: Some walkthroughs here.

docs/UsingIteration.rst

@@ -2,4 +2,47 @@
 Using Iteration
 ***************
 
-TBD
+There are some operations that may return an arbitrary large list of results. For 
+example: ``GET /groups/<id>/attributes`` returns all the attributes of the 
+group object with the given id.  It's possible (if not common in practice) that the 
+group may contain hundreds or more attributes.
+
+If you desire to retrieve the list of attributes in batches (say you are developing a 
+user interface that has a "get next page" style button), you can use iteration.
+
+This is accomplished by adding query parameters to the request the limit the number of
+items returned and a marker parameter that identifies where the iteration should start 
+off.
+
+Let's flush out our example by supposing the group with UUID <id> has 1000 attributes 
+named "a0000", "a0001", and so on.
+
+If we'd like to retrieve just the first 100 attributes, we can add a limit value to the 
+request like so:
+
+``GET /groups/<id>/attributes?Limit=100``
+
+Now the response will return attributes "a0000", "a0001", through "a0099". 
+
+To get the next hundred, use the URL-encoded name of the last attribute received as the 
+marker value for the next request:
+
+``GET /groups/<id>/attributes?Limit=100&Marker="a0099"``
+
+This request will return attributes "a0100", "a0101", through "a0199".
+
+Repeat this pattern until less the limit items are returned.  This indicates that you've
+completed the iteration through all elements of the group.
+
+Iteration is also supported for links in a group, and the groups, datasets, and datatypes
+collections.
+
+Related Resources
+=================
+
+* :doc:`AttrOps/GET_Attributes`
+* :doc:`GroupOps/GET_Groups`
+* :doc:`GroupOps/GET_Links`
+* :doc:`DatasetOps/GET_Datasets`
+* :doc:`DatatypeOps/GET_Datatypes`
+

docs/WhatsNew/index.rst

@@ -2,9 +2,14 @@
 What's New 
 ###################
 
-All kinds of new stuff!
+This is the first release of h5serv.  
 
-.. toctree::
-   :maxdepth: 2
+Significant features:
 
-   0.1
+ * An implementation of the REST API as outlined in the RESTful HDF5 paper: 
+   http://www.hdfgroup.org/pubs/papers/RESTful_HDF5.pdf 
+ * A simple DNS Server that maps DNS domains to HDF5 collections (i.e. files)
+ * Utilities to convert native HDF5 files to HDF5-JSON and HDF5-JSON to HDF5
+ * UUID and timestamp extensions for HDF5 datasets, groups, and committed data types
+
+

docs/conf.py

@@ -56,7 +56,7 @@
 # The short X.Y version.
 version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.1'
+release = '0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -25,7 +25,6 @@ Contents:
    Utilities
    WhatsNew/index
    Tutorials/index
-   BugReports/index
    FAQ/index
    License/index