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.
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.
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:
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