Skip to content

A
atlas
Commit b6b6f945 by apoorvnaik Committed by Madhan Neethiraj
Options

ATLAS-1370: Atlas REST API document generation with enunciate

Signed-off-by: 's avatarMadhan Neethiraj <madhan@apache.org>
parent ce54e8a4
Showing with 206 additions and 91 deletions
build-tools/src/main/resources/enunciate.xml
......@@ -17,39 +17,27 @@
-->
<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://enunciate.codehaus.org/schemas/enunciate-1.29.xsd">
<api-import pattern="org.apache.atlas.web.resources.*"/>
<services>
<rest defaultRestSubcontext="/api/atlas/">
<custom-resource-parameter-annotation
qualifiedName="org.glassfish.jersey.media.multipart.FormDataParam"/>
</rest>
</services>
<webapp disabled="true"/>
xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.8.0.xsd">
<title>Atlas REST API</title>
<description> Atlas exposes a variety of REST endpoints to work with types, entities, lineage and data discovery.</description>
<api-classes>
<include pattern="org.apache.atlas.web.rest.*"/>
<include pattern="org.apache.atlas.model.*"/>
</api-classes>
<modules>
<disable-rule id="csharp.warnings"/>
<disable-rule id="c.warnings"/>
<disable-rule id="obj-c.warnings"/>
<docs docsDir="apidocs" title="Apache Data Governance APIs"
includeDefaultDownloads="true" includeExampleXml="false"
disableRestMountpoint="true" forceExampleJson="true">
</docs>
<basic-app disabled="true"/>
<c disabled="true"/>
<csharp disabled="true"/>
<jaxws-ri disabled="true"/>
<jersey disabled="true"/>
<obj-c disabled="true"/>
<amf disabled="true"/>
<gwt disabled="true"/>
<jboss disabled="true"/>
<object-c disabled="true"/>
<rubby disabled="true"/>
<java-client disabled="true"/>
<jaxws-client disabled="true"/>
<xml forceExampleJson="true"/>
<jaxws-support disabled="false"/>
<cxf disabled="false" enableJaxrs="true" enableJaxws="true"/>
<jaxws disabled="false"/>
<swagger/>
<jackson/>
<jackson1 disabled="true"/>
<c-xml-client disabled="true"/>
<java-json-client disabled="true"/>
<csharp-xml-client disabled="true"/>
<java-xml-client disabled="true"/>
<javascript-client disabled="true"/>
<ruby-json-client disabled="true"/>
<gwt-json-overlay disabled="true"/>
<php-xml-client disabled="true"/>
<php-json-client disabled="true"/>
<jaxws disabled="true"/>
</modules>
</enunciate>
\ No newline at end of file
docs/src/site/twiki/index.twiki
......@@ -55,7 +55,8 @@ allows integration with the whole enterprise data ecosystem.
---++ API Documentation
* <a href="api/rest.html">REST API Documentation</a>
* <a href="api/v2/index.html">REST API Documentation</a>
* <a href="api/rest.html">Legacy API Documentation</a>
---++ Developer Setup Documentation
* [[EclipseSetup][Developer Setup: Eclipse]]
......
intg/src/main/java/org/apache/atlas/AtlasErrorCode.java
......@@ -65,15 +65,14 @@ public enum AtlasErrorCode {
UNKNOWN_ATTRIBUTE(400, "ATLAS40034E", "Attribute {0} not found for type {1}"),
SYSTEM_TYPE(400, "ATLAS40035E", "{0} is a System-type"),
INVALID_STRUCT_VALUE(400, "ATLAS40036E", "not a valid struct value {0}"),
INSTANCE_LINEAGE_INVALID_PARAMS(400, "ATLAS40037E", "Invalid lineage query parameters passed {0}: {1}"),
// All Not found enums go here
TYPE_NAME_NOT_FOUND(404, "ATLAS4041E", "Given typename {0} was invalid"),
TYPE_GUID_NOT_FOUND(404, "ATLAS4042E", "Given type guid {0} was invalid"),
EMPTY_RESULTS(404, "ATLAS4044E", "No result found for {0}"),
INSTANCE_GUID_NOT_FOUND(404, "ATLAS4045E", "Given instance guid {0} is invalid/not found"),
INSTANCE_LINEAGE_INVALID_PARAMS(404, "ATLAS4046E", "Invalid lineage query parameters passed {0}: {1}"),
INSTANCE_LINEAGE_QUERY_FAILED(404, "ATLAS4047E", "Instance lineage query failed {0}"),
DISCOVERY_QUERY_FAILED(404, "ATLAS4048E", "Discovery query failed {0}"),
INSTANCE_CRUD_INVALID_PARAMS(404, "ATLAS4049E", "Invalid instance creation/updation parameters passed : {0}"),
INSTANCE_BY_UNIQUE_ATTRIBUTE_NOT_FOUND(404, "ATLAS40410E", "Instance {0} with unique attribute {1} does not exist"),
......@@ -87,9 +86,10 @@ public enum AtlasErrorCode {
INTERNAL_ERROR(500, "ATLAS5001E", "Internal server error {0}"),
INDEX_CREATION_FAILED(500, "ATLAS5002E", "Index creation failed for {0}"),
INDEX_ROLLBACK_FAILED(500, "ATLAS5003E", "Index rollback failed for {0}"),
FAILED_TO_OBTAIN_TYPE_UPDATE_LOCK(500, "ATLAS5004E", "Failed to get the lock; another type update might be in progress. Please try again"),
FAILED_TO_OBTAIN_IMPORT_EXPORT_LOCK(500, "ATLAS5005E", "Another import or export is in progress. Please try again"),
NOTIFICATION_FAILED(500, "ATLAS5005E", "Failed to notify for change {0}");
DISCOVERY_QUERY_FAILED(500, "ATLAS5004E", "Discovery query failed {0}"),
FAILED_TO_OBTAIN_TYPE_UPDATE_LOCK(500, "ATLAS5005E", "Failed to get the lock; another type update might be in progress. Please try again"),
FAILED_TO_OBTAIN_IMPORT_EXPORT_LOCK(500, "ATLAS5006E", "Another import or export is in progress. Please try again"),
NOTIFICATION_FAILED(500, "ATLAS5007E", "Failed to notify for change {0}");
private String errorCode;
private String errorMessage;
......
pom.xml
......@@ -483,6 +483,7 @@
<skipITs>false</skipITs>
<skipDocs>true</skipDocs>
<skipSite>true</skipSite>
<skipEnunciate>true</skipEnunciate>
<projectBaseDir>${project.basedir}</projectBaseDir>
<jetty-maven-plugin.stopWait>10</jetty-maven-plugin.stopWait>
......@@ -524,22 +525,6 @@
</profile>
<profile>
<id>jdk7</id>
<activation>
<jdk>[1.7,1.8)</jdk>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<version>1.29</version>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>dist</id>
<activation>
<activeByDefault>false</activeByDefault>
......@@ -1433,6 +1418,14 @@
<version>${fastutil.version}</version>
</dependency>
<!-- API documentation -->
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core-annotations</artifactId>
<version>2.8.0</version>
</dependency>
<!-- supports simple auth handler -->
<dependency>
<groupId>org.apache.httpcomponents</groupId>
......@@ -1682,6 +1675,20 @@
<artifactId>aspectj-maven-plugin</artifactId>
<version>1.8</version>
</plugin>
<plugin>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-maven-plugin</artifactId>
<version>2.8.0</version>
<executions>
<execution>
<goals>
<goal>docs</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
......
webapp/pom.xml
......@@ -40,33 +40,6 @@
<profiles>
<profile>
<id>jdk7</id>
<activation>
<jdk>[1.7,1.8)</jdk>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>docs</goal>
</goals>
<phase>site</phase>
</execution>
</executions>
<configuration>
<!-- the directory where to put the docs -->
<docsDir>${project.build.directory}/apidocs</docsDir>
<configFile>${basedir}/../src/build/enunciate.xml</configFile>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<!-- default profile is for external HBase and Solr - hence not packaging those jars -->
<id>dist</id>
<activation>
......@@ -399,6 +372,12 @@
<groupId>org.apache.atlas</groupId>
<artifactId>atlas-server-api</artifactId>
</dependency>
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core-annotations</artifactId>
</dependency>
</dependencies>
<build>
......@@ -663,6 +642,18 @@
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-maven-plugin</artifactId>
<configuration>
<configFile>${project.parent.basedir}/build-tools/src/main/resources/enunciate.xml</configFile>
<enunciateArtifactId/>
<docsDir>${project.build.directory}/api/v2/</docsDir>
<source>1.7</source>
<target>1.7</target>
<skipEnunciate>${skipEnunciate}</skipEnunciate>
</configuration>
</plugin>
</plugins>
</build>
</project>
webapp/src/main/java/org/apache/atlas/web/resources/AdminResource.java
......@@ -52,17 +52,26 @@ import javax.inject.Singleton;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.ws.rs.*;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.util.*;
import java.util.Collection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.locks.ReentrantLock;
import static org.apache.atlas.repository.converters.AtlasInstanceConverter.toAtlasBaseException;
/**
* Jersey Resource for admin operations.
*/
......
webapp/src/main/java/org/apache/atlas/web/rest/DiscoveryREST.java
......@@ -30,6 +30,9 @@ import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
/**
* REST interface for data discovery using dsl or full text search
*/
@Path("v2/search")
@Singleton
public class DiscoveryREST {
......@@ -40,6 +43,17 @@ public class DiscoveryREST {
this.atlasDiscoveryService = discoveryService;
}
/**
* Retrieve data for the specified DSL
* @param query DSL query
* @param limit limit the result set to only include the specified number of entries
* @param offset start offset of the result set (useful for pagination)
* @return Search results
* @throws AtlasBaseException
* @HTTP 200 On successful DSL execution with some results, might return an empty list if execution succeeded
* without any results
* @HTTP 400 Invalid DSL or query parameters
*/
@GET
@Path("/dsl")
@Consumes(Servlets.JSON_MEDIA_TYPE)
......@@ -53,6 +67,17 @@ public class DiscoveryREST {
return ret;
}
/**
* Retrieve data for the specified fulltext query
* @param query Fulltext query
* @param limit limit the result set to only include the specified number of entries
* @param offset start offset of the result set (useful for pagination)
* @return Search results
* @throws AtlasBaseException
* @HTTP 200 On successful FullText lookup with some results, might return an empty list if execution succeeded
* without any results
* @HTTP 400 Invalid fulltext or query parameters
*/
@GET
@Path("/fulltext")
@Consumes(Servlets.JSON_MEDIA_TYPE)
......
webapp/src/main/java/org/apache/atlas/web/rest/LineageREST.java
......@@ -37,6 +37,9 @@ import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Context;
/**
* REST interface for an entity's lineage information
*/
@Path("v2/lineage")
@Singleton
public class LineageREST {
......@@ -59,6 +62,9 @@ public class LineageREST {
* @param depth - number of hops for lineage
* @return AtlasLineageInfo
* @throws AtlasBaseException
* @HTTP 200 If Lineage exists for the given entity
* @HTTP 400 Bad query parameters
* @HTTP 404 If no lineage is found for the given entity
*/
@GET
@Path("/{guid}")
......
webapp/src/main/java/org/apache/atlas/web/rest/TypesREST.java
......@@ -18,6 +18,8 @@
package org.apache.atlas.web.rest;
import com.google.inject.Inject;
import com.webcohesion.enunciate.metadata.rs.ResponseCode;
import com.webcohesion.enunciate.metadata.rs.StatusCodes;
import org.apache.atlas.exception.AtlasBaseException;
import org.apache.atlas.model.SearchFilter;
import org.apache.atlas.model.typedef.AtlasBaseTypeDef;
......@@ -46,20 +48,28 @@ import javax.ws.rs.core.Context;
import java.util.List;
import java.util.Set;
/**
* REST interface for CRUD operations on type definitions
*/
@Path("v2/types")
@Singleton
public class TypesREST {
private final AtlasTypeDefStore typeDefStore;
@Inject
public TypesREST(AtlasTypeDefStore typeDefStore) {
this.typeDefStore = typeDefStore;
}
/**
* Get type definition by it's name
* @param name Type name
* @return Type definition
* @throws AtlasBaseException
* @HTTP 200 Successful lookup by name
* @HTTP 404 Failed lookup by name
*/
@GET
@Path("/typedef/name/{name}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -69,6 +79,13 @@ public class TypesREST {
return ret;
}
/**
* @param guid GUID of the type
* @return Type definition
* @throws AtlasBaseException
* @HTTP 200 Successful lookup
* @HTTP 404 Failed lookup
*/
@GET
@Path("/typedef/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -82,6 +99,8 @@ public class TypesREST {
* Bulk retrieval API for all type definitions returned as a list of minimal information header
* @return List of AtlasTypeDefHeader {@link AtlasTypeDefHeader}
* @throws AtlasBaseException
* @HTTP 200 Returns a list of {@link AtlasTypeDefHeader} matching the search criteria
* or an empty list if no match.
*/
@GET
@Path("/typedefs/headers")
......@@ -98,6 +117,7 @@ public class TypesREST {
* Bulk retrieval API for retrieving all type definitions in Atlas
* @return A composite wrapper object with lists of all type definitions
* @throws Exception
* @HTTP 200 {@link AtlasTypesDef} with type definitions matching the search criteria or else returns empty list of type definitions
*/
@GET
@Path("/typedefs")
......@@ -110,6 +130,14 @@ public class TypesREST {
return typesDef;
}
/**
* Get the enum definition by it's name (unique)
* @param name enum name
* @return enum definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the enum definition by it's name
* @HTTP 404 On Failed lookup for the given name
*/
@GET
@Path("/enumdef/name/{name}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -119,6 +147,14 @@ public class TypesREST {
return ret;
}
/**
* Get the enum definition for the given guid
* @param guid enum guid
* @return enum definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the enum definition by it's guid
* @HTTP 404 On Failed lookup for the given guid
*/
@GET
@Path("/enumdef/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -129,6 +165,14 @@ public class TypesREST {
}
/**
* Get the struct definition by it's name (unique)
* @param name struct name
* @return struct definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the struct definition by it's name
* @HTTP 404 On Failed lookup for the given name
*/
@GET
@Path("/structdef/name/{name}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -138,6 +182,14 @@ public class TypesREST {
return ret;
}
/**
* Get the struct definition for the given guid
* @param guid struct guid
* @return struct definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the struct definition by it's guid
* @HTTP 404 On Failed lookup for the given guid
*/
@GET
@Path("/structdef/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -147,6 +199,14 @@ public class TypesREST {
return ret;
}
/**
* Get the classification definition by it's name (unique)
* @param name classification name
* @return classification definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the classification definition by it's name
* @HTTP 404 On Failed lookup for the given name
*/
@GET
@Path("/classificationdef/name/{name}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -156,6 +216,14 @@ public class TypesREST {
return ret;
}
/**
* Get the classification definition for the given guid
* @param guid classification guid
* @return classification definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the classification definition by it's guid
* @HTTP 404 On Failed lookup for the given guid
*/
@GET
@Path("/classificationdef/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -165,7 +233,14 @@ public class TypesREST {
return ret;
}
/**
* Get the entity definition by it's name (unique)
* @param name entity name
* @return Entity definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the entity definition by it's name
* @HTTP 404 On Failed lookup for the given name
*/
@GET
@Path("/entitydef/name/{name}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -175,6 +250,14 @@ public class TypesREST {
return ret;
}
/**
* Get the Entity definition for the given guid
* @param guid entity guid
* @return Entity definition
* @throws AtlasBaseException
* @HTTP 200 On successful lookup of the the entity definition by it's guid
* @HTTP 404 On Failed lookup for the given guid
*/
@GET
@Path("/entitydef/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
......@@ -184,9 +267,7 @@ public class TypesREST {
return ret;
}
/******************************************************************/
/** Bulk API operations **/
/******************************************************************/
/* Bulk API operation */
/**
* Bulk create APIs for all atlas type definitions, only new definitions will be created.
......@@ -195,6 +276,8 @@ public class TypesREST {
* @return A composite wrapper object with lists of type definitions that were successfully
* created
* @throws Exception
* @HTTP 200 On successful update of requested type definitions
* @HTTP 400 On validation failure for any type definitions
*/
@POST
@Path("/typedefs")
......@@ -211,6 +294,8 @@ public class TypesREST {
* @param typesDef A composite object that captures all type definition changes
* @return A composite object with lists of type definitions that were updated
* @throws Exception
* @HTTP 200 On successful update of requested type definitions
* @HTTP 400 On validation failure for any type definitions
*/
@PUT
@Path("/typedefs")
......@@ -227,6 +312,8 @@ public class TypesREST {
* Bulk delete API for all types
* @param typesDef A composite object that captures all types to be deleted
* @throws Exception
* @HTTP 204 On successful deletion of the requested type definitions
* @HTTP 400 On validation failure for any type definitions
*/
@DELETE
@Path("/typedefs")
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment