Endpoint Metadata

We've added a new way to define endpoints in the Aptify services layer. 

The new endpoint framework consists of metadata for:

• the route for the endpoint
• the input we're expecting from the client
• the output the client should expect
• the business logic for the endpoint
• optional security that can be applied to the endpoint

Having all of these items in metadata allows them to be modified easily for configurations.  By strictly defining the input and outputs in metadata we can also generate rich documentation that clearly defines what APIs we're exposing through the services layer.  

The endpoints follow REST based conventions.  This means we rely on HTTP to inform us of what's going on, as that protocol is widely understood throughout the developer community.  The HTTP verbs tell us what the end point is going to do:

• GET - read an existing resource
• POST - create a new resource
• PATCH - update part of an existing resource
• DELETE - delete an existing resource
• PUT - replace the entire representation of a resource with a new one.  

We also use HTTP status codes to tell us if a request was successful or if there was an error.  

Let's look at a sample endpoint definition and break down the parts.  We'll go into each part in greater detail on other pages.

{
  "endpoints": {							
    "getAllCountries": {
      "route": {
        "httpMethod": "GET",
        "segments": {
          "Countries": {
            "isLiteral": true,
            "type": "string"
          }
        }
      },
      "inputEntityDefinition": null,
      "outputEntityDefinition": {
        "isCollection": true,
        "name": "Country",
        "fields": {
          "id": {
            "type": "long"
          },
          "country": {
            "type": "string"
          },
          "ISOCode": {
            "type": "string"
          }
        }
      },
      "businessLogic": {
        "allCountriesRetrieval": {
          "executionType": "processFlow",
          "processFlowProperties": {
            "processFlowName": "Execute Data Object",
            "processFlowParameters": {
              "DataObjectName": "spGeteBusiness6_0CountryList"
            }
          }
        }
      },
      "security": {
        "AllowAnonymous": {
          "type": "AllowAnonymous"
        }
      }
    }
  }
}

 
All Endpoint.json files have a single 'endpoints' block.  Its children are the end points we're defining.  
Here we have one endpoint named 'getAllCountries' and we see its 5 parts:  route, input, output, business logic and security.  
 
 
 
 
 
 
 
 
This end point accepts no input.  
 
The output for this end point is a collection of objects with fields for the id, country, and ISO code.  
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
This end point executes a single process flow that calls a database object.  The output from that process flow will be translated into 
the output entity definition.
 
 
 
 
 
 
 
 
 
Anyone is allowed to call this end point.  By default all end points require authentication.  

Attached please find a set of sample JSON calls for e-Business services (filename: Ebiz6EndpointsCollection.zip).

Note that you may encounter an error like this when calling one of the endpoints:

{
"errorCode": 992,
"message": "",
"responseIdentifier": "a5bf2053-85a8-4b78-ba3a-8dc7fa1718f1",
"type": "AntiForgery"
}

In that case, see this page for information on how to modify your configuration to support CSRF protection. If you are testing in a non-production environment, you can disable this security feature by modifying this key in the web.config to False: Aptify.Services.Csrf.EnableCSRFProtection