If you have a comment on this topic, contact Aptify Documentation. If you want to return to the Aptify Community Site, please click here.

Endpoint Metadata

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

The new endpoint framework consists of metadata for:

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.  

Metadata File Location

By default, all json metadata files exist under the 'ebusiness\json\' directory at the root of your services site. This location can be overridden with the application setting 'Aptify.Services.Metadata.Json.Directory' in web.config. Underneath this location, each endpoint file should be within its own folder and the filename should end with 'Endpoint.json'. There can only be one file that ends with 'Endpoint.json' in each directory, but that file may define many end points and reference many other files.

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.  

Mutational endpoints (POST, PATCH, DELETE, PUT) are not thread safe against the same resource.  This is by design. Even if we built something into the framework to account for this, the system cannot guarantee operations would be processed in the order the caller wanted, as network latency can change the order of when requests reach the server.

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.  

Behind the Scenes

Aptify will take the metadata in the JSON files and generate code that exposes the desired endpoint.  By default, controllers are compiled in a random directory within the Windows temp directory.  After compilation the output (cs, dll, and pdb) is copied into the bin directory.  If problems arise with using the Windows temp directory this can be overridden by specifying a different path in the application setting 'Aptify.Services.TempDirectory' in web.config.  All generated files end with the name 'GeneratedController.<fileExtension>'.  Metadata files are examined during application startup.  If they are newer than the output files in the bin directory they will be regenerated.  

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

Copyright © 2014-2019 Aptify - Confidential and Proprietary