<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

<document>
  <header>
    <title>HCatalog REST API </title>
  </header>
  <body>

   <section>
      <title>Introduction </title>
       <p>This document describes HCatalog REST API.
        As shown in the figure below, developers make HTTP requests to access
        <a href="http://hadoop.apache.org/mapreduce/">Hadoop MapReduce</a>,
        <a href="http://pig.apache.org/">Pig</a>,
        <a href="http://hive.apache.org/">Hive</a>, and
        <a href="http://incubator.apache.org/hcatalog/docs/r0.2.0/cli.html">
        HCatalog DDL</a> from within applications.
        Data and code used by this API is maintained in
        <a href="http://hadoop.apache.org/hdfs/">HDFS</a>.  HCatalog DDL commands
        are executed directly when requested.
        MapReduce, Pig, and Hive jobs are placed in queue by
        and can be monitored for progress or stopped as required.
        Developers specify a location
        in HDFS into which Pig, Hive, and MapReduce results should be placed.</p>
       <figure src="images/TempletonArch.jpg" align="left" alt="Templeton Architecture"/>
   </section>

    <section>
       <title>URL format </title>
       <p>HCatalog's REST resources are accessed using the following URL format:</p>
       <p><code>http://</code><em>yourserver</em><code>/templeton/v1/</code><em>resource</em></p>
       <p>where "<em>yourserver</em>" is replaced with your server name, and
          "<em>resource</em>" is replaced by the HCatalog
          resource name.</p>
       <p>For example, to check if the server is running you could
          access the following URL:</p>
       <p><code>http://www.myserver.com/templeton/v1/status</code></p>
    </section>

   <section>
      <title>Security </title>
       <p>The current version supports two types of security:</p>
       <ul>
       <li>Default security (without additional authentication)</li>
       <li>Authentication via
           <a href="http://web.mit.edu/kerberos/">Kerberos</a></li>
       </ul>
     <section>
       <title>Standard Parameters </title>
       <p>Every REST resource can accept the following parameters to
         aid in authentication: </p>
         <ul>
         <li>user.name: The user name as a string.
             Only valid when using default security. </li>
         <li>SPNEGO credentials: When running with Kerberos authentication. </li>
         </ul>
     </section>

     <section>
       <title>Security Error Response</title>
       <p>If the user.name parameter is not supplied when required, 
        the following error will be returned: </p>
<source>
{
  "error": "No user found.  Missing user.name parameter."
}
</source>
     </section>

   </section>

   <section>
      <title>WebHDFS and Code Push</title>
      <p>Data and code that are used by HCatalog's REST resources must first be placed in
         Hadoop.  When placing files into HDFS is required you can use
         whatever method is most convienient for you.  We suggest WebHDFS since it provides
         a REST interface for moving files into and out of HDFS.</p>
   </section>

   <section>
        <title>Error Codes and Responses</title>
        <p>The server returns the following HTTP status codes.</p>
        <ul>
        <li><strong>200 OK:</strong> Success!</li>
        <li><strong>400 Bad Request:</strong> The request was invalid.</li>
        <li><strong>401 Unauthorized:</strong> Credentials were missing or incorrect.</li>
        <li><strong>404 Not Found:</strong> The URI requested is invalid or the
                    resource requested does not exist.</li>
        <li><strong>500 Internal Server Error:</strong> We received an unexpected result.</li>
        <li><strong>503 Busy, please retry:</strong> The server is busy.</li>
        </ul>
        <p>Other data returned directly by the server is returned in JSON format.
         JSON responses are limited to 1MB in size.  Responses over this limit must be
         stored into HDFS using provided options instead of being directly returned.
         If an HCatalog DDL command might return results greater than 1MB, it's
         suggested that a corresponding Hive request be executed instead.</p>
   </section>

   <section>
       <title>Log Files</title>
       <p>The server creates three log files when in operation:</p>
       <ul>
       <li><strong>templeton.log</strong> is the log4j log.  This the main log the application
        writes to.</li>
       <li><strong>templeton-console.log</strong> is what Java writes to stdout when the server is
        started.  It is a small amount of data, similar to "hcat.out".</li>
       <li><strong>tempelton-console-error.log</strong> is what Java writes to stderr, similar to
        "hcat.err".</li>
       </ul>
       <p>In the tempelton-log4j.properties file you can set the location of these logs using the
        variable templeton.log.dir.  This log4j.properties file is set in the server startup script.</p>
   </section>

   <section>
    <title>Project Name</title>
    <p>The original work to add REST APIs to HCatalog was called Templeton.  For backward compatibility
       the name still appears in URLs, log file names, etc.  The Templeton name is taken from a character
       in the award-winning children's novel Charlotte's Web, by E. B. White.  The novel's protagonist is a pig named
       Wilber.  Templeton is a rat who helps Wilber by running errands and making deliveries as 
       requested by Charlotte while spinning her web.</p>
   </section>
  </body>
</document>
