Merge pull request #31 from geoadmin/feat-PB-1810-talk-about-endpoints-instead-of-services

PB-1810 Replace "service" by "endpoint" #patch

Author: asteiner-swisstopo

docs/get-layer-legend.md

@@ -1,13 +1,14 @@
 # Get Layer Legend
 
-With a layer ID (or technical name), this service can be used to
-retrieve a legend.
+This endpoint provides the legend of a given layer in the form of HTML markup.
+A legend is what is shown when you click the info button on a layer in the map viewer.
+It contains a description of the layer, the actual legend explaining the meaning of the different colors and symbols, and additional metadata.
 
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/legend" method="GET" />
 
 ## Request Details
 
-To interact with the Layer Legend service, you need to provide specific parameters in your request.
+To interact with the legend endpoint, you need to provide specific parameters in your request.
 These parameters are divided into **Path Parameters**, which are required and part of the URL, and **Query Parameters**, which are optional and modify the behavior of the request.
 
 ### Path Parameters

docs/get-layer-metadata.md

@@ -1,13 +1,12 @@
 # Get Layer Metadata
 
-This service provides metadata for all the available layers in the
-GeoAdmin API.
+This endpoint provides metadata for all layers that match a search query.
 
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer" method="GET" />
 
 ## Request Details
 
-To interact with the Layer Metadata service, you need to provide specific parameters in your request.
+To interact with the metadata endpoint, you need to provide specific parameters in your request.
 This endpoint only has **Query Parameters**, which are optional and modify the behavior of the request.
 
 ### Query Parameters
@@ -21,9 +20,8 @@ This endpoint only has **Query Parameters**, which are optional and modify the b
 
 ## Response Details
 
-A request to the Layer Metadata service returns a **JSON** composed by a list of object literals representing the **layers** and a set of metadata **attributes** associated to each layer.
-
-Here is a description of the data one can find in the above response.
+The response constains a list of all the layers matching the query.
+For each layer, there are some general identification properties
 
 | Field        | Description                                                                             |
 | ------------ | --------------------------------------------------------------------------------------- |
@@ -32,7 +30,8 @@ Here is a description of the data one can find in the above response.
 | `idGeoCat`   | The associated metadata ID in [GeoCat](http://www.geocat.ch/geonetwork/srv/eng/geocat). |
 | `layerBodId` | The technical name or BOD ID.                                                           |
 
-**Attributes:** Metadata attributes associated with a given layer.
+and attributes listing more metaadata
+
 | Field | Description |
 | ------------ | --------------------------------------------------------------------------------------- |
 | `wmsResource` | The WMS resource of the layer. |

docs/identify-features.md

@@ -1,6 +1,6 @@
 # Identify Features
 
-Use this service to discover features at a specific location.
+Use this endpoint to discover features at a specific location.
 
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/identify" method="GET" />
 
@@ -10,7 +10,7 @@ No more than 50 features can be retrieved per request.
 
 ## Request Details
 
-To interact with the identify features service, you need to provide specific parameters in your request.
+To interact with the `identify` endpoint, you need to provide specific parameters in your request.
 This endpoint only has query parameters that modify the behavior of the request, some are required and some are optional.
 
 ### Query Parameters
@@ -44,7 +44,7 @@ The following table summarize the various combinations:
 
 ### layerDefs syntax
 
-To list the available attributes together with their types and examples values, use the layer [attribute service](/docs/get-layer-attributes).
+To list the available attributes together with their types and examples values, use the [layer attribute endpoint](/docs/get-layer-attributes).
 
 Define the `layerDefs` parameter in JSON format like `{"<layername>":"<filter_expression>"}`.
 
@@ -428,7 +428,7 @@ example='{
 
 ## Examples: Reverse Geocoding
 
-The service identify can be used for Reverse Geocoding operations.
+The `identify` endpoint can be used for reverse geocoding operations.
 
 Perform an identify request to find the districts intersecting a given envelope geometry (no buffer):