The basics

One of ECHO's goals is to increase access to Earth Science data and services by providing a system with a machine-to-machine interface. For that reason, ECHO provides an Application Programming Interface (API). This section describes how to communicate with ECHO using its Web Services API.

Locating the ECHO Web Services

To access a particular service through the ECHO Web Services API, refer to the Reference page of the ECHO website http://api.echo.nasa.gov/echo/apis.html

The preferred method of interacting with ECHO is via our REST interfaces detailed here

If you prefer to use SOAP services you can use the following guidelines.
The table below shows each ECHO service and a brief description of its capabilities. The ECHO 10.0 Web Services API documentation describes in detail the services along with their operations and parameters, and is currently available online at:  http://api.echo.nasa.gov/echo/ws/v10/index.html 
To access the Web Service Description Language (WSDL) document that describes a service, attach the suffix .wsdl from the API page following this format: http://api.echo.nasa.gov/echo-wsdl/v10/<Service Endpoint>.wsdl. Service Endpoints are found in Table 1.

Table 1. Description of Client Partner-Related ECHO Web Services

To see a detailed breakdown of functionality by user type and role type within ECHO, see Appendix B, Functional Breakdown By User/Role Type.

ECHO Error Handling

The ECHO 9.0/10.10 Web Service API has advanced error-reporting capabilities. Refer to Appendix E, ECHO Error Handling for a list of specific faults and their meanings.

Globally Unique Identifiers (GUIDS)

ECHO uses Globally Unique Identifiers (GUIDs) to uniquely identify objects within ECHO. Each GUID is a dd
is a mostly random number with a large number of unique keys that is assigned to each item by ECHO. A GUID is normally a 16-byte (128-bit) number in hexadecimal form.
ECHO uses GUIDs to identify items such as users, providers, contacts, orders, etc. Client applications use these GUIDs to find and operate on items using the ECHO API. Client applications should avoid displaying a GUID to the end user, as it is a machine-to-machine identifier. Most of the items in ECHO also accommodate a name preferred by the user; the client application can simply map from the item's user-displayed name to its actual GUID. This pairing of machine-readable GUID and human-readable name is referred to as a NameGuid in the ECHO API. You can retrieve a list of NameGuids for most items.
In almost all cases (with the notable exception of the Taxonomy API), the GUID on an item should be null when the item is sent to ECHO to be created. Once ECHO creates the item, it will generate a new GUID for the item and return it to the client.
Note: ECHO introduced the formalized GUID pattern after the system had been under development for some years. Due to this, you may find that some GUIDs for ECHO objects (typically users and providers) do not follow the standard.

ECHO Entities

This section describes several high-level concepts that will help you understand the ECHO system. The following is a selected list of entities.  

Users

The most basic entity in the ECHO system is a user. Each user is identified by a unique user name. There are two types of users: registered users and guests. Registered users can save information they plan to use in their next session. Guests have the ability to do many of the things registered users can do, but they cannot count on persistent access to information across sessions in addition to other limitations.

Roles

ECHO regulates access privileges based on the concept of user roles. User roles are a way to grant a user access to the system. These roles facilitate greater flexibility with operation-level authorization and allow certain users the ability to have more than one role without having more than one account in the system.

Provider Role

As a Client Partner, your role is the provider role. You may have one or more provider roles, each of which is associated with one provider in the ECHO system. Your provider roles allow you to access and update information about the providers with which they are associated. For example, if you have a provider role for Oak Ridge National Laboratory (ORNL), then you can use the UpdateProviders operation of the ProviderService to update the contact information for ORNL.
If you have more than one provider role, you must tell the system which provider you currently want to represent. This is the "provider context". The provider context indicates the current provider that you represent, and as the name implies, it is to this provider that the provider-oriented operations in the system are applied.

Note: If you are associated with only one provider role, the system assumes the provider associated with that one provider role is specified in the user‟s "provider context."

Administrator Role

A user can only be associated with one instance of this role. This role allows the user to access and update information about any user and any provider. Essentially, this role should allow the user full access to almost anything in the system and available through the current API. Users assigned this role should read the ECHO 10.10 Operations Guide as well as this document.

Queries

A query in the ECHO system is the term used for search and retrieval of science metadata stored by ECHO. You can search ECHO by calling the ExecuteQuery operation on the CatalogService—refer to Chapter 4, 'Querying for Earth Science Metadata for a detailed discussion of queries'
NOTE: You can search on collections (referred to as a Discovery Search) or on granules (referred to as an Inventory Search).

Results

ECHO automatically generates a ResultSet after an ECHO query. Every result set in ECHO has a unique identifier (that is, a GUID) within the system.
You can execute multiple queries simultaneously. Result sets from all these queries will be available by name (ResultSetGUID); however, result sets may be removed from ECHO without notice in a reasonable amount of time. Since guests are not allowed to save results in ECHO, the results are not available after the guest completes the ECHO session. Results can be retrieved by using the GetQueryResults operation in the Catalog Service.

Catalog Items

A catalog item is any metadata item (granule or collection) that is available for ordering from the ECHO system. To find the desired catalog items to order, queries are performed against the ECHO database. The results of a query may return several granules or collections. Catalog items are identified by a catalog item GUID (CatalogItemId, which is an assigned XML metadata tag).
To see the possible required/optional options for a catalog item, invoke the GetCatalogItemOrderInformation operation on the OrderManagementService passing the catalog item GUIDs of interest.
If a URL is provided, you (Client Partners) may retrieve the data from that URL as a direct link or obtain the data accessing instruction via the URL.

Orders

An order is a collection of catalog items that you, as a Client Partner, wish to have and would like to order from a Data Provider. Each item in the order is associated with a quantity and any options available for that item. Within ECHO, a user creates an order and then adds, deletes, and updates each item in the order before submitting the
order to ECHO. Orders can also be created and submitted in a single web service API call (CreateAndSubmitOrder). Registered Client Partners can look at the status of their orders, as well as the history of all their submitted and shipped orders.
The collection of catalog items that comprises an order does not have to belong to one provider, but can span many providers. When organizing providers and catalog items within an order, another concept called a ―provider order‖ is used. A provider order is a collection of all items in the original order that belong to a single provider.
Since an order may contain orders from multiple providers, an order can consist of one or more provider orders. Each provider order can consist of one or more catalog items that belong to the same provider. To identify a specific provider order, you need the GUID of the order that includes that provider order and the GUID of the Data Partner associated with that provider order.
When a full order is submitted, ECHO splits the user's order into separate provider orders and submits each provider order to the associated Data Provider.
The OrderManagementService allows users to create and change orders, provider orders, or individual catalog items. However, once the SubmitOrder operation is executed for a particular order within the OrderManagementService, the user can no longer execute any further changes on that order. A registered user may look at the current and historical status of any of their submitted orders.
Once a provider order is submitted to the appropriate provider, the status of that order can be changed in two ways:

• The Data Provider can send an immediate response, whether they will or will not accept the order, to an order submission.
• The Data Provider can wait and asynchronously use the OrderProcessingService to change the status of an order after they have had time to process the order.

Order Options (Used by Data Partners)

Data Partners use order options to describe the structure of the data to request of the client as well as how to display the order form to the client. They use ECHO Forms to perform both of these functions. For details about ECHO Forms, refer to the ECHO Forms schema and other information at  http://www.echo.nasa.gov/data_partners/data_tools.shtml.
Option definitions contain a name, scope, deprecated flag, and an ECHO Form. Every option definition for a provider has a unique name. The scope indicates whether it is a system-level option definition or provider-level option definition. The deprecated flag indicates that you, as a Data Partner, have made that option definition obsolete. The deprecated flag indicates to clients that they should no longer use the option definition. The form part of the option definition contains an ECHO Form.

As of ECHO 10.1 data providers are able to supply two additional option definition fields: description and sort key. The new fields are available in a new extended option definition type, OptionDefinition2. The description field allows data providers to supply users with a longer description of the type or purpose of an option definition and it is intended for client display. The sort key allows data providers to indicate display order of their option definitions to users and is intended to be used by clients to sort option definitions before displaying to users.

The OptionSelection is the data from the client for a specific option definition. The selection should be put in the content part of the option selection. Options are also used in ECHO to describe authenticators and options for ordering data from a provider.

Groups

The term groups refers to an aggregating mechanism in ECHO that allows Client Partners to associate a Group name with a given set of users. When a group is created, the group's owner specifies an ECHO user to be the group's manager. However, group managers can be added and removed after creation by other group
managers. After becoming a member of a group, a user can be granted access to restricted metadata via the Data Management Service.

Controlling Access to Metadata

ECHO provides a mechanism for controlling access to metadata. Data partners may restrict or permit users of the ECHO system to take action upon metadata. These actions currently include viewing, browsing, and ordering metadata. Data partners may create conditions which are used to specify characteristics of metadata. For example:

• 30 days old
• the month of September
• qaFlag2 value 3

When combined with a Comparator, Action, and Data Holding to create rules, conditions become powerful.
If a rule is a restriction, it applies to the entire ECHO populace. If a rule is a permission it applies only to members of the group specified.
In addition to the restrictions and permissions, a collection can be set to be restricted from viewing, browsing, and ordering by all users except the ones acting on behalf of the provider who owns the collection by simply setting its visibility flag to 'RESTRICT'. This restriction can be removed by simply change its visibility flag back to 'OPEN'.
The restriction applied on the collection will also be applied on all its granules.
As a Client Partner, you may wish to remind your users of these data restrictions.

Extended Services

ECHO Extended Services allows partners to advertise and register web service interfaces, implementations, GUIs, and advertisements.