You are here: Resources

SAS Data Loader 3.1 for Hadoop: REST API Reference

Resources

REST APIs provide access to resources, or data entities, using URI paths. To use a REST API, a request is made using standard HTTP methods such as GET, PUT, POST, and DELETE. Representations are returned as a JSON response accompanied by a status code. Note that the user must have appropriate credentials to access resources through the SAS Data Loader for Hadoop REST API.

HTTP Methods

The primary HTTP verbs that are used in the SAS Data Loader for Hadoop REST API are GET, PUT, POST, and DELETE. Here is a brief description.

GET is used to retrieve, or read, a representation of a resource. GET returns a representation in JSON with a response code of 200 (OK) . If an error occurs, HTTP returns a status of 400 (Bad request), 404 (Not found), or 500 (Internal server error).

PUT is used to update a resource. HTTP returns a status 201 (Success) if the update is successful or a status 404 (Not found) if the resource could not be found. If an error occurs, HTTP returns a status of 400 (Bad request), 404 (Not found), or 500 (Internal server error).

POST is used for creation of new resources. On successful creation, HTTP returns a status of 200 (OK). If there is an error in the request, HTTP returns status of 404 (Not found) or 500 (Internal server error).

DELETE is used to delete a resource identified by a URI. On successful deletion, HTTP returns status 204 (Server found and deleted). If the resource cannot be found, an HTTP status 500 (Internal server error) is returned.

Resource /

The / resource is the root resource that is used to get top-level links.

Methods: GET

GET / : Get Links

Get Links returns the list of root level links. This resource supports the HEAD method as well.

Request

GET http://www.example.com/SASDataLoader/rest/

The request also supports the Accept request headers, which supports the following media types:

application/vnd.sas.links+json (which is really the Links type)

Link Relations

rel	HTTP Method	Description
directives	GET	Gets the collection of directives. URI: /directives Type: vnd.sas.collection

Response 200, 500

Collection /directives

The /directives collection is the collection of directives that have been created in SAS Data Loader for Hadoop.

Methods: GET

GET /directives : Get Directives

Get Directives gets a list of all directives filtered by the query parameters.

Request

GET http://www.example.com/SASDataLoader/rest/directives

Query Parameters

Name	Type	Description
?directiveFolderPath	string	The full path to the directive to be returned. It includes the directive's name and returns a single directive.
?sasFolderPath	string	The path to the SAS folder to be returned. It returns the collection of directives that the user has read-access to within the given folder.
?start	integer	The starting index of the first item in a page. The index is 0-based. The default is 0.
?limit	integer	The maximum number of items to return in this page of results. The actual number of returned items might be less if the collection has been exhausted. The default is 10.

The request also supports the Accept request headers, which supports the following media types:

application/json (which is really the Collection type)
application/vnd.sas.collection+json

Response 200, 400, 500

Resource /directives/{directiveId}

The /directives/{directiveId} resource gets information about the directive.

URL Parameters

Name	Type	Description
{directiveId}	string	The directive's ID.

Methods: GET

GET /directives/{directiveId} : Get Directive

Get Directive gets information about a directive. HEAD is also supported for this resource.

Request

GET http://www.example.com/SASDataLoader/rest/directives/{directiveId}

The request also supports the Accept request headers, which supports the following media types:

application/json
application/vnd.sas.dataloader.directive+json
application/vnd.sas.dataloader.directive.summary+json

Response: The directive.

Response Headers

Last-Modified - the timestamp (EEE, dd MMM yyyy HH:mm:ss GMT) when the resource was last modified.

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

application/vnd.sas.dataloader.directive+json
application/vnd.sas.dataloader.directive.summary+json
application/json which is a application/vnd.sas.dataloader.directive+json

Collection /jobs

The /jobs collection represents all the executions (past and present) of directives in SAS Data Loader for Hadoop.

Methods: POST

POST /jobs : Run Directive

The Run Directive runs a directive.

Request

POST http://www.example.com/SASDataLoader/rest/jobs

Query Parameters

Name	Type	Description
?directive	string	The ID of the directive to be executed. This is an optional parameter and is not needed if "directivePath" is specified.
?directivePath	string	The path of the directive to be executed. This is an optional parameter and is not needed if "directive" is specified.

The request also supports the Accept request headers, which supports the following media types:

application/json
application/vnd.sas.dataloader.job+json

Response

Returns information about the job that was created including the job ID.

Response Headers

Location - The location of the new resource (for example, http://www.example.com/SASDataLoader/rest/jobs/1234)

Last-Modified - The timestamp (EEE, dd MMM yyyy HH:mm:ss GMT) when the resource was last modified.

Cache-Control - Because the elapsed time is updated for each request until the job is completed (stopTimeStamp is present), the Cache-Control is set to "no-cache."

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

application/vnd.sas.dataloader.job+json
application/json which is application/vnd.sas.dataloader.job+json

Resource /jobs/{jobId}

The /job/{jobId} resource represents an execution of a directive. Getting the job resource returns the state of the job.

URL Parameters

Name	Type	Description
{jobId}	string	The ID of the job.

Methods: GET, DELETE

GET /jobs/{jobId} : Get Job

Get Job gets the job which is used to provide an update on the job's state. Supports the HEAD method as well.

Request

GET http://www.example.com/SASDataLoader/rest/jobs/{jobId}

The request also supports the Accept request headers, which supports the following media types:

application/json
application/vnd.sas.dataloader.job+json.

Response:

The current information about the job.

Response Headers

Last-Modified - the timestamp (EEE, dd MMM yyyy HH:mm:ss GMT) when the resource was last modified.

Cache-Control - Because the elapsed time is updated for each request until the job is completed (stopTimeStamp is present), the Cache-Control is set to "no-cache."

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

application/json which is application/vnd.sas.dataloader.job+json
application/vnd.sas.dataloader.job+json

DELETE /jobs/{jobId} : DeleteJob

Delete Job deletes the job. All information related to the job is deleted.

Request

DELETE http://www.example.com/SASDataLoader/rest/jobs/{jobId}

Response Codes 204, 500

Resource /jobs/{jobId}/state

The /job/{jobId} resource represents the state of the job.

URL Parameters

Name	Type	Description
{jobId}	string	The ID of the job.

Methods: GET, PUT

GET /jobs/{jobId}/state : Get Job State

Get Job State gets the job's state. The state is a text value. For more information, see state in the application/vnd.sas.dataloader.job Members table.

Request

GET http://www.example.com/SASDataLoader/rest/jobs/{jobId}/state

The request also supports the Accept request headers, which supports the following media type:

text/plain

Response:

This operation returns the job state. The possible values are listed for the state member of application/vnd.dataloader.job.

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

text/plain

PUT /jobs/{jobId}/state : Cancel Job

Cancel Job cancels the job.

Request: PUT http://www.example.com/SASDataLoader/rest/jobs/{jobId}/state

Query Parameter

Name	Type	Description
?value	string	The only valid value is canceled and is required.

The request also supports the Accept request headers, which supports the following media type:

text/plain

Response:

Returns the current state of the job. If the job was already complete, the state might be completed or failed or some other value. If the cancel request has not been processed, the state will not have changed. The state can also be canceling indicating the job has started canceling or canceled indicating the job has canceled.

Response Codes 200, 400, 404, 500

Response Media Types

This operation returns the following media type representation by setting the Accept: header of the request:

text/plain

Resource /jobs/{jobId}/log

The /jobs/{jobId}/log resource is the job's log.

URL Parameters

Name	Type	Description
{jobId}	string	The job's ID.

Methods: GET

GET /jobs/{jobId}/log: Get Job Log

Get Job Log gets the job's log.

Request

GET http://www.example.com/SASDataLoader/rest/jobs/{jobId}/log

The request also supports the Accept request headers, which supports the following media type:

text/plain

Response:

Returns the job's log.

Response Codes 200, 404

Response Media Types

This operation can return the following media type representation by setting the Accept: header of the request:

text/plain

Resource /jobs/{jobId}/error

The /jobs/{jobId}/error resource gets the error information for a job.

URL Parameters

Name	Type	Description
{jobId}	string	The job's ID.

Methods: GET

GET /jobs/{jobId}/error : Gets the job's error.

Gets the job's error.

Request

GET http://www.example.com/SASDataLoader/rest/jobs/{jobId}/error

The request also supports the Accept request headers, which supports the following media types:

application/json
application/vnd.sas.error+json

Response:

Returns an application/vnd.sas.error+json with the following values:

errorCode - always 0
httpStatusCode - either 200 (OK) if there was no error or 500 (Server Error) if there was an error
details - detailed information about this error. It is a list of strings that have not been localized,
version - version information for this error format (integer, value 1)
links - a list of com.sas.commons.rest.Link objects as per Link representation standards. The link relations are up, self, and log.

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

application/vnd.sas.error
application/json which is application/vnd.sas.error

Collection /jobs/{jobId}/results

The /jobs/{jobId}/results collection is the job's results.

URL Parameters

Name	Type	Description
{jobId}	string	The job's ID.

Methods: GET

GET /jobs/{jobId}/results : Gets the collection of a job's results

Gets the collection of a job's results. This collection is not paged.

Request

GET http://www.example.com/SASDataLoader/rest/jobs/{jobId}/results

The request also supports the Accept request headers, which supports the following media types:

application/json
application/vnd.sas.collection+json

Response:

The collection of the job's results which are instances of application/vnd.sas.dataloader.job.result. To view the result, use the view link.

Response Codes 200, 404, 500

Response Media Types

This operation can return the following media type representations by setting the Accept: header of the request:

application/vnd.sas.collection
application/json

Documentation Feedback: yourturn@sas.com
Note: Always include the Doc ID when providing documentation feedback.

Doc ID: Resources.html