Understanding Web API and SOA
Aptify’s Service Oriented Architecture (SOA), Aptify SOA, provides connectivity to Aptify’s business functionality. It is used by Aptify applications, including the Aptify web interface, Aptify Point of Sale, and Aptify Mobile for Members, as the path to the Aptify business layer. Aptify’s next-generation e-Business application and all new applications are being built with Aptify SOA.
Aptify SOA is also used to support integrations with other systems. Aptify has integrated with third party applications using Aptify SOA. Customers also use Aptify SOA to integrate with different systems in their organization.
Aptify’s applications are built using a metadata-driven framework that provides tremendous flexibility in configuration while maintaining an upgrade path. The same framework that Aptify uses to build the applications is available to our customers to build is available to our customers for configuring existing applications and for building completely new applications. Aptify SOA is in integral part of that framework.
In order to support all of these requirements, Aptify SOA must provide comprehensive access to Aptify’s business layer. It must also be secure, robust and performant. Many clients will use Aptify SOA including web applications, server applications and mobile devices. Finally, it must be easily consumable by those clients. To meet these requirements, Aptify SOA uses RESTful services built with Microsoft’s ASP.NET Web API.
This topic is focused on the common uses for Aptify SOA including authentication, pulling data from Aptify and pushing data back into Aptify. To accomplish this, Aptify SOA provides generic service endpoints that can provide secure access to Aptify without overwhelming the user with hundreds of endpoints. As an example, Aptify provides a Viewing System where Views are created to retrieve data from the system. Users create Views with the appropriate fields, filters and sorts defined. Aptify SOA provides a single endpoint, AptifyViews, that can be used to execute the View and return its results. With this endpoint, it becomes quick and easy to create a dataset needed for an integration scenario and provide the endpoint to the integrator. Similarly, the CRUD operations for all Entities go through common Entity endpoints, with the name of the Entity. Once the basic endpoints are understood, they can be used to access information throughout Aptify.
What Is Web API
ASP.NET Web API is a framework for exposing data and services to different devices. Moreover, ASP.NET Web API is an ideal platform for building RESTful services over the .NET Framework. It uses the full features of HTTP. Additional information about ASP.NET Web API can be found here: http://www.asp.net/web-api.
Features of ASP.NET Web API
- It supports convention-based CRUD Action since it works with HTTP verbs GET, POST, PUT and DELETE.
- Responses have an Accept header and HTTP status code.
- Responses are formatted by Web API’s MediaTypeFormatter into JSON or XML. Aptify SOA uses JSON as the default format for responses.
- It supports in-line documentation of services and uses that information to generate online documentation that can be accessed via URL. Example: https://<servicebase>/AptifyServicesAPI/help
REST
REST stands for Representational State Transfer. This is a protocol for exchanging data over a distributed environment. The main idea behind REST is to treat distributed services as resources and use simple HTTP protocols to perform various operations on those resources.
Now the basic CRUD operations are mapped to the HTTP protocols in the following manner:
- GET: This maps to the R (Retrieve) part of the CRUD operation. This will be used to retrieve the required data (representation of data) from the remote resource.
- PUT: This maps to the U (Update) part of the CRUD operation. This protocol will update the current representation of the data on the remote server.
- POST: This maps to the C (Create) part of the CRUD operation. This will create a new entry for the current data that is being sent to the server.
- DELETE: This maps to the D (Delete) part of the CRUD operation. This will delete the specified data from the remote server.
Aptify APIs
Aptify offers several APIs to configure applications built within Aptify and to integrate with other applications and systems.
Aptify Web JavaScript API
Aptify provides a rich JavaScript API, separated into UI and non-UI sections. Non-UI methods can be used in any JavaScript execution environment, not just browsers, because those methods do not require any browser objects. Node.js is a server-side JavaScript execution environment that could utilize Aptify’s non-UI JavaScript API. UI functions require an HTML5 browser. The JavaScript API is often easier to use and provides more functionality (for example, leveraging Local Storage and supporting composite operations in a single method) than Aptify SOA, especially for developers used to working with .NET or other programming languages. The JavaScript API utilizes Aptify SOA to connect to the Aptify business layer. When JavaScript is available, it is the preferred API for integrating with Aptify.
Aptify SOA
Aptify’s Web Service API provides RESTful services for secure, performant and comprehensive access to Aptify’s business layer. It powers Aptify’s JavaScript API and several Aptify products, like Aptify Web, Aptify Point of Sale and Aptify Mobile for Members. All new applications built with Aptify will utilize Aptify SOA either directly or indirectly, through Aptify’s JavaScript API.
Aptify Business Layer (.NET)
Aptify’s business layer is built with Microsoft .NET and provides an object oriented API. When building configurations in the business layer, much can be done with Aptify metadata. Where metadata ends or code is more efficient, Aptify’s business layer provides plug-in support for all functionality that is designed to be configured. Business objects can be extended by inheriting from the Aptify class and overriding methods that require pre-processing, post-processing or complete replacement. For integrations with 3rd party components, like address verification systems, Aptify builds a plug-in architecture that makes it easy to extend existing components or build plug-ins to new products. With this flexibility built into the architecture, it is easier to evolve applications with best-of-breed third party integrations.
Aptify’s Metadata-based Framework
Aptify’s Framework uses metadata to build much of its application functionality and configurations. Business Logic, data structures and user-interface are all defined in metadata through an Administrator/Developer user interface. New applications can be built and existing application can be configured with little or no coding. Aptify’s APIs are metadata-aware, automatically extending access, based on security settings, to new definitions and configurations to existing metadata.
More information about the APIs is available in Developing for Aptify, the Aptify Software Development Kit (SDK), and Aptify training classes. The remainder of this document is focused on Aptify SOA.
Aptify SOA Common Operations
This document will focus on the common operations for web service integrations:
- Authentication
- Retrieving Data from Aptify
- Modifying Data in Aptify
Copyright © 2014-2019 Aptify - Confidential and Proprietary