Repository: falcon Updated Branches: refs/heads/asf-site 8e49379d2 -> 31b1d7e6a
http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/InstanceSuspend.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/InstanceSuspend.twiki b/trunk/releases/master/src/site/twiki/restapi/InstanceSuspend.twiki new file mode 100644 index 0000000..2ba8663 --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/InstanceSuspend.twiki @@ -0,0 +1,44 @@ +---++ POST /api/instance/suspend/:entity-type/:entity-name + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Suspend instances of an entity. + +---++ Parameters + * :entity-type can either be a feed or a process. + * :entity-name is name of the entity. + * start is the start time of the instance(s) that you want to refer to + * end is the end time of the instance(s) that you want to refer to + * lifecycle <optional param> can be Eviction/Replication(default) for feed and Execution(default) for process. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results +Results of the suspend command. + +---++ Examples +---+++ Rest Call +<verbatim> +POST http://localhost:15000/api/instance/suspend/process/SampleProcess?colo=*&start=2012-04-03T07:00Z&end=2014-04-03T07:00Z&doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "instances": [ + { + "details": "", + "endTime": "2013-10-21T15:15:01-07:00", + "startTime": "2013-10-21T15:14:32-07:00", + "cluster": "primary-cluster", + "logFile": "http:\/\/localhost:11000\/oozie?job=0000070-131021115933395-oozie-rgau-W", + "status": "SUCCEEDED", + "instance": "2012-04-03T07:00Z" + } + ], + "requestId": "default\/ff07e45b-b6da-4f47-ae96-9182bd8a7e53\n", + "message": "default\/SUSPEND\n", + "status": "SUCCEEDED" +} +</verbatim> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/MetadataList.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/MetadataList.twiki b/trunk/releases/master/src/site/twiki/restapi/MetadataList.twiki new file mode 100644 index 0000000..98abf46 --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/MetadataList.twiki @@ -0,0 +1,31 @@ +---++ GET api/metadata/discovery/:type/list + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Get all dimensions of specified type. + +---++ Parameters + * :type Valid dimension types are cluster_entity,feed_entity, process_entity, user, colo, tags, groups, pipelines + * cluster <optional query param> Show dimensions related to this cluster. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + + +---++ Results +List of dimensions that match requested type [and cluster]. + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/metadata/discovery/process_entity/list?cluster=primary-cluster&doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "results": ["sampleIngestProcess","testProcess","anotherProcess"], + "totalSize": 3 +} +</verbatim> + http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/MetadataRelations.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/MetadataRelations.twiki b/trunk/releases/master/src/site/twiki/restapi/MetadataRelations.twiki new file mode 100644 index 0000000..b29fd2a --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/MetadataRelations.twiki @@ -0,0 +1,46 @@ +---++ GET api/metadata/discovery/:dimension-type/:dimension-name/relations + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Get all relations of a specific dimension. + +---++ Parameters + * :type Valid dimension types are cluster_entity,feed_entity, process_entity, user, colo, tags, groups, pipelines + * :name Name of the dimension. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results +Get all relations of a specific dimension. + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/metadata/discovery/process_entity/sample-process/relations?doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "timestamp":"2014-09-09T01:31Z", + "userWorkflowEngine":"pig", + "name":"sample-process", + "type":"PROCESS_ENTITY", + "userWorkflowName":"imp-click-join-workflow", + "version":"1.0.9", + "inVertices":[ + {"name":"clicks-feed","type":"FEED_ENTITY","label":"input"}, + {"name":"impression-feed","type":"FEED_ENTITY","label":"input"}, + {"name":"sample-process\/2014-01-01T01:00Z","type":"PROCESS_INSTANCE","label":"instance-of"} + ], + "outVertices":[ + {"name":"Critical","type":"TAGS","label":"classified-as"}, + {"name":"testPipeline","type":"PIPELINES","label":"pipeline"}, + {"name":"primary-cluster","type":"CLUSTER_ENTITY","label":"runs-on"}, + {"name":"imp-click-join2","type":"FEED_ENTITY","label":"output"}, + {"name":"imp-click-join1","type":"FEED_ENTITY","label":"output"}, + {"name":"falcon-user","type":"USER","label":"owned-by"} + ] +} +</verbatim> http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/ResourceList.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/ResourceList.twiki b/trunk/releases/master/src/site/twiki/restapi/ResourceList.twiki new file mode 100644 index 0000000..34c2c6f --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/ResourceList.twiki @@ -0,0 +1,93 @@ +---+ RESTful Resources + +---++ Resource List + * <a href="#REST_Call_on_Entity_Resource">REST Call on Entity Resource</a> + * <a href="#REST_Call_on_Feed_and_Process_Instances">REST Call on Feed/Process Instances</a> + * <a href="#REST_Call_on_Admin_Resource">REST Call on Admin Resource</a> + * <a href="#REST_Call_on_Lineage_Graph">REST Call on Lineage Graph Resource</a> + * <a href="#REST_Call_on_Metadata_Resource">REST Call on Metadata Resource</a> + +---++ Authentication + +When security is off (Pseudo/Simple), the authenticated user is the username specified in the user.name query +parameter. If the user.name parameter is not set, the server may either set the authenticated user to a default web +user, if there is any, or return an error response. + +When security is on (kerberos), authentication is performed by Kerberos SPNEGO. + +Below are examples using the curl command tool. + +Authentication when security is off (Pseudo/Simple): +<verbatim> +curl -i "http://<HOST>:<PORT>/<PATH>?[user.name=<USER>&]<PARAM>=..." +</verbatim> + +Authentication using Kerberos SPNEGO when security is on: +<verbatim> +curl -i --negotiate -u : "http://<HOST>:<PORT>/<PATH>?<PARAM>=..." +</verbatim> + +See also: [[../Security.twiki][Security in Falcon]] + +The current version of the rest api's documentation is also hosted on the Falcon server and Prism Server (in distributed mode) at the url http://<HOST>:<PORT>/docs + +---++ REST Call on Admin Resource + +| *Call Type* | *Resource* | *Description* | +| GET | [[AdminStack][api/admin/stack]] | Get stack of the server | +| GET | [[AdminVersion][api/admin/version]] | Get version of the server | +| GET | [[AdminConfig][api/admin/config/:config-type]] | Get configuration information of the server | + +---++ REST Call on Entity Resource + +| *Call Type* | *Resource* | *Description* | +| POST | [[EntityValidate][api/entities/validate/:entity-type]] | Validate the entity | +| POST | [[EntitySubmit][api/entities/submit/:entity-type]] | Submit the entity | +| POST | [[EntityUpdate][api/entities/update/:entity-type/:entity-name]] | Update the entity | +| POST | [[EntitySubmitAndSchedule][api/entities/submitAndSchedule/:entity-type]] | Submit & Schedule the entity | +| POST | [[EntitySchedule][api/entities/schedule/:entity-type/:entity-name]] | Schedule the entity | +| POST | [[EntitySuspend][api/entities/suspend/:entity-type/:entity-name]] | Suspend the entity | +| POST | [[EntityResume][api/entities/resume/:entity-type/:entity-name]] | Resume the entity | +| DELETE | [[EntityDelete][api/entities/delete/:entity-type/:entity-name]] | Delete the entity | +| GET | [[EntityStatus][api/entities/status/:entity-type/:entity-name]] | Get the status of the entity | +| GET | [[EntityDefinition][api/entities/definition/:entity-type/:entity-name]] | Get the definition of the entity | +| GET | [[EntityList][api/entities/list/:entity-type]] | Get the list of entities | +| GET | [[EntitySummary][api/entities/summary/:entity-type/:cluster]] | Get instance summary of all entities | +| GET | [[EntityDependencies][api/entities/dependencies/:entity-type/:entity-name]] | Get the dependencies of the entity | +| GET | [[FeedSLA][api/entities/sla-alert/:entity-type]] | Get pending feed instances which missed sla | +| GET | [[FeedLookup][api/entities/lookup/feed/]] | Get feed for given path | + +---++ REST Call on Feed and Process Instances + +| *Call Type* | *Resource* | *Description* | +| GET | [[InstanceRunning][api/instance/running/:entity-type/:entity-name]] | List of running instances. | +| GET | [[InstanceParams][api/instance/params/:entity-type/:entity-name]] | List of entity instances along with their workflow params. | +| GET | [[InstanceList][api/instance/list/:entity-type/:entity-name]] | List of instances | +| GET | [[InstanceStatus][api/instance/status/:entity-type/:entity-name]] | Status of a given instance | +| POST | [[InstanceKill][api/instance/kill/:entity-type/:entity-name]] | Kill a given instance | +| POST | [[InstanceSuspend][api/instance/suspend/:entity-type/:entity-name]] | Suspend a running instance | +| POST | [[InstanceResume][api/instance/resume/:entity-type/:entity-name]] | Resume a given instance | +| POST | [[InstanceRerun][api/instance/rerun/:entity-type/:entity-name]] | Rerun a given instance | +| GET | [[InstanceLogs][api/instance/logs/:entity-type/:entity-name]] | Get logs of a given instance | +| GET | [[Triage][api/instance/triage/:entity-type/:entity-name]] | Triage an instance to see it's stuck lineage | +| GET | [[InstanceSummary][api/instance/summary/:entity-type/:entity-name]] | Return summary of instances for an entity | +| GET | [[InstanceDependency][api/instance/dependencies/:entity-type/:entity-name]] | Return dependent instances for a given instance | + +---++ REST Call on Metadata Lineage Resource + +| *Call Type* | *Resource* | *Description* | +| GET | [[Graph][api/metadata/lineage/serialize]] | dump the graph | +| GET | [[AllVertices][api/metadata/lineage/vertices/all]] | get all vertices | +| GET | [[Vertices][api/metadata/lineage/vertices?key=:key&value=:value]] | get all vertices for a key index | +| GET | [[Vertex][api/metadata/lineage/vertices/:id]] | get the vertex with the specified id | +| GET | [[VertexProperties][api/metadata/lineage/vertices/properties/:id?relationships=:true]] | get the properties of the vertex with the specified id | +| GET | [[AdjacentVertices][api/metadata/lineage/vertices/:id/:direction]] | get the adjacent vertices or edges of the vertex with the specified direction | +| GET | [[AllEdges][api/metadata/lineage/edges/all]] | get all edges | +| GET | [[Edge][api/metadata/lineage/edges/:id]] | get the edge with the specified id | +| GET | [[EntityLineage][api/metadata/lineage/entities?pipeline=:name]] | Get lineage graph for processes and feeds in the specified pipeline | + +---++ REST Call on Metadata Discovery Resource + +| *Call Type* | *Resource* | *Description* | +| GET | [[MetadataList][api/metadata/discovery/:dimension-type/list]] | list of dimensions | +| GET | [MetadataRelations][api/metadata/discovery/:dimension-type/:dimension-name/relations]] | Return all relations of a dimension | http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/Triage.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/Triage.twiki b/trunk/releases/master/src/site/twiki/restapi/Triage.twiki new file mode 100644 index 0000000..9ff95c8 --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/Triage.twiki @@ -0,0 +1,45 @@ +---++ GET api/instance/triage/:entity-type/:entity-name + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Given a feed/process instance this command traces it's ancestors to find what all ancestors have failed. It's useful if +lot of instances are failing in a pipeline as it then finds out the root cause of the pipeline being stuck. + + +---++ Parameters + * :entity-type type of entity(feed/process). + * :entity-name name of the feed/process. + * :start instance time of the entity instance. + * :colo <optional param> name of the colo on which you want to triage + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results +It returns a json graph + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/instance/triage/feed/my-feed?start=2015-03-02T00:00Z&colo=local&doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "vertices": ["(FEED) my-feed (2015-03-02T00:00Z) [Unavailable]", "(PROCESS) producer-process (2015-03-01T10:00Z) [TIMEDOUT]", "(FEED) input-feed-for-producer (2015-03-01T00:00Z) [Available]"], + "edges": + [ + { + "from" : "(PROCESS) producer-process (2015-03-01T10:00Z) [TIMEDOUT]", + "to" : "(FEED) my-feed (2015-03-02T00:00Z) [Unavailable]", + "label" : "produces" + }, + { + "from" : "(FEED) input-feed-for-producer (2015-03-01T00:00Z) [Available]", + "to" : "(PROCESS) producer-process (2015-03-01T10:00Z) [TIMEDOUT]", + "label" : "consumed by" + } + ] +} +</verbatim> http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/Vertex.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/Vertex.twiki b/trunk/releases/master/src/site/twiki/restapi/Vertex.twiki new file mode 100644 index 0000000..82f5bfb --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/Vertex.twiki @@ -0,0 +1,36 @@ +---++ GET api/metadata/lineage/vertices/:id + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Gets the vertex with specified id. + +---++ Parameters + * :id is the unique id of the vertex. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results +Vertex with the specified id. + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/metadata/lineage/vertices/4?doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "results": [ + { + "timestamp":"2014-04-21T20:55Z", + "name":"sampleIngestProcess", + "type":"process-instance", + "version":"2.0.0", + "_id":4, + "_type":"vertex" + } + ] +} +</verbatim> http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/VertexProperties.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/VertexProperties.twiki b/trunk/releases/master/src/site/twiki/restapi/VertexProperties.twiki new file mode 100644 index 0000000..11c64b5 --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/VertexProperties.twiki @@ -0,0 +1,34 @@ +---++ GET api/metadata/lineage/vertices/properties/:id?relationships=:true + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Gets the properties of the vertex with specified id. + +---++ Parameters + * :id is the unique id of the vertex. + * :relationships has default value of false. Pass true if relationships should be fetched. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results + Properties associated with the specified vertex. + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/metadata/lineage/vertices/properties/40004?relationships=true&doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "results": + { + "timestamp":"2014-04-25T22:20Z", + "name":"local", + "type":"cluster-entity" + }, + "totalSize":3 +} +</verbatim> http://git-wip-us.apache.org/repos/asf/falcon/blob/31b1d7e6/trunk/releases/master/src/site/twiki/restapi/Vertices.twiki ---------------------------------------------------------------------- diff --git a/trunk/releases/master/src/site/twiki/restapi/Vertices.twiki b/trunk/releases/master/src/site/twiki/restapi/Vertices.twiki new file mode 100644 index 0000000..643e6e9 --- /dev/null +++ b/trunk/releases/master/src/site/twiki/restapi/Vertices.twiki @@ -0,0 +1,38 @@ +---++ GET api/metadata/lineage/vertices?key=:key&value=:value + * <a href="#Description">Description</a> + * <a href="#Parameters">Parameters</a> + * <a href="#Results">Results</a> + * <a href="#Examples">Examples</a> + +---++ Description +Get all vertices for a key index given the specified value. + +---++ Parameters + * :key is the key to be matched. + * :value is the associated value of the key. + * doAs <optional query param> allows the current user to impersonate the user passed in doAs when interacting with the Falcon system. + +---++ Results +All vertices matching given property key and a value. + +---++ Examples +---+++ Rest Call +<verbatim> +GET http://localhost:15000/api/metadata/lineage/vertices?key=name&value=sampleIngestProcess&doAs=joe +</verbatim> +---+++ Result +<verbatim> +{ + "results": [ + { + "timestamp":"2014-04-21T20:55Z", + "name":"sampleIngestProcess", + "type":"process-instance", + "version":"2.0.0", + "_id":4, + "_type":"vertex" + } + ], + "totalSize": 1 +} +</verbatim> \ No newline at end of file
