This section will use an example REST endpoint for illustrative purposes: Information to Document This section outlines the information that should be documented, categorized by hierarchy level: Hierarchy Name Description Example Server Address The HTTP root URL where the service will be provided. In most situations, it should contain only the protocol and domain name without virtual directories. It will be used to construct absolute URL string for REST services. Server Server The name of the REST server. It should be brief NWIS-WQ Name and meaningful. Server Server A description of the REST server. National Water Information Description System (NWIS) Web Services Server Status The status of the service. Select if Operational “Operational” the server is available, otherwise choose Assumed Operational if not supplied. “Offline”. Server Provider The name of the organization that provides the USGS services. Server Contact addresses for technical contacts. johndoe@usgs.gov Service Service URL This is a relative URL without the Server Address /Station/search? Template part. It should contain everything needed by the server except the base server address and parameters. Service Service A name of the service. It should be unique Station Name within the server and the name should only contain alphanumeric characters without white spaces. This will be used as the unique identifier of the service. Service Description A more detailed description of the service. Returns listing of stations in WQX XML format that given data filters. Service Shared This is a flag that determines how the service Public Option will be published. A private service will not be published, a shared service will be published to only authenticated users, and a public service will be viewable by any users. Service HTTP Identifies which http method is expected for the GET Method request. will be assumed by default if this “GET” is not specified.
This section will use an example REST endpoint for illustrative purposes: Information to Document This section outlines the information that should be documented, categorized by hierarchy level: Hierarchy Name Description Example Server Address The HTTP root URL where the service will be provided. In most situations, it should contain only the protocol and domain name without virtual directories. It will be used to construct absolute URL string for REST services. Server Server Name The name of the REST server. It should be brief and meaningful. NWIS-WQ Server Server Description A description of the REST server. National Water Information System (NWIS) Web Services Server Status The status of the service. Select “Operational” if the server is available, otherwise choose “Offline”. Assumed Operational if not supplied. Operational Server Provider The name of the organization that provides the services. USGS Server Contact addresses for technical contacts. johndoe@usgs.gov Service Service URL Template This is a relative URL without the Server Address part. It should contain everything needed by the server except the base server address and parameters. /Station/search? Service Service Name A name of the service. It should be unique within the server and the name should only contain alphanumeric characters without white spaces. This will be used as the unique identifier of the service. Station Service Description A more detailed description of the service. Returns listing of stations in WQX XML format that given data filters. Service Shared Option This is a flag that determines how the service will be published. A private service will not be published, a shared service will be published to only authenticated users, and a public service will be viewable by any users. Public Service HTTP Method Identifies which http method is expected for the request. “GET” will be assumed by default if this is not specified. GET
REST_Guidance_v1.1.docx