Developer Portal
This chapter describes optional, Sentinet Developer Portal feature. The feature is required only when the owner of the Sentinet product (typically API Provider) wants to offer API consumers a specialized self-service "Developer Portal" User Experience to help them learn and consume provider's APIs. Sentinet Developer Portal Web Application is a built on top of the open source Umbraco CMS (Content Management System) system, and is typically branded (white-labeled) by the API Provider (owner of the Sentinet product). Figure below shows optional Sentinet components (in green color) that support Developer Portal feature.
Configuration
To configure a new or update an existing Developer Portal Web Application:
Start the Developer Portal Configuration Application from Developer Portal Configuration Windows shortcut or launch DevPortalConfiguration.exe located in the root of the installation directory. This will open the Developer Portal Configuration Wizard, starting with the Repository Database page.
Note
You have to be logged in to the machine as a member of the local Administrators group and start Developer Portal Configuration Wizard with option Run as administrator on the machine that has tightened security settings.
Enter the database server machine name or the machine network address in the Server Name field. If the SQL Server is configured with Windows Integrated authentication and your Windows account has an access right to update an existing database on this server, select Windows Integrated authentication in the System Administrator account section. Alternatively, select the SQL Server authentication option and provide a SQL Server Username/Password account credentials with sufficient (to create and update) databases access rights. These credentials will be used by this Repository Configuration application while it is running. Select existing Repository Database from the Database Name drop-down list. Drop-down list will be populated with all databases available on the selected Database Server only if System Administrator account is provided correctly.
If the Developer Portal Web Application is planned to use Windows Integrated access to the Repository Database, select Windows Integrated authentication in the Repository Application account section (default setting). Alternatively, select the SQL Server authentication option and provide a Username/Password for the SQL Server account that will be granted access to the Repository database. If SQL Server account does not exist, it will be automatically created. These credentials will be used by the running instance of the Repository Web Application.
Click Next button to navigate to Monitoring Database page.
This is the page, where Sentinet can be configured with advanced settings suitable for high-performance, high-loads environment(s). Leave checkmark to Attach to existing stand-alone Monitoring database in default, unchecked state.
Note
This tutorial covers Sentinet standard deployment model, when a single Repository Database is used to handle all Sentinet data storage and management tasks. Sentinet User Guide covers in details all other deployment models supported by the Sentinet product.
Click Next button to Developer Portal Database page. This page is used to create a new or use an existing Developer Portal Content Management (CMS) database. The settings on this page are similar to Repository Database page (step 2) above, except that they are meant to create new (or use existing) Developer Portal Database.
Click Next button to navigate to Developer Portal Application page. This page is used to create a new or configure existing Developer Portal Web Application.
Enter database server name or the network address in the Server Name field where Developer Portal database will reside. When Use existing database option above is selected, the Configuration Wizard will search for all databases configured on the SQL Server identified by the Server Name field. Database Name field will change to a drop-down list of discovered database names. Default server name is the current machine name.
Select the authentication modes for both the System Administrator and Developer Portal Web Application's accounts.
Select the IIS Server Web Site that will host Repository Web Application.
Select SSL settings. Configuration Wizard automatically uses SSL settings currently configured with selected IIS server's Web Site. If the Web Site is not configured with SSL, you may select an X.509 certificate from the list of available valid certificates (from the drop-down list) or request the Configuration Wizard to generate a new, self-signed, SSL certificate (click the Create button to generate new certificate).
Select Web Application settings. Input a name for the Developer Portal Web Application (default is SentinetDevPortal) and select an IIS server's application pool from the list of available Application Pools. By default, the Configuration Wizard will create its own Application Pool, SentinetDevPortalAppPool dedicated to the Developer Portal Web Application and configure it with the IIS server's standard, ApplicationPoolIdentity (a low-privileged pseudo-machine account).
Check Require SSL box (recommended and checked by default) to restrict access to Developer Portal Web Application with SSL. Developer Portal Web Application will automatically redirect all traffic to https addresses when Require SSL setting is turned on.
Click Next button to navigate to Developer Portal Settings page.
Enter the length of API Keys (number of characters) generated by Sentinet for any API Consumer applications that will require API Keys (default is 64 characters).
Enter expiration of API Keys (in number of days) generated by Sentinet for any API Consumer applications that will require API Keys.
Click Finish to start the configuration process. Progress of the configuration process should now be displayed.
Click Close button (ignore Save Configuration button that is used for automated deployments described in the Installation Guide). If the Launch Application box is checked (default value), your default browser application is started with the login page of the default Sentinet Developer Portal Console (Note that Microsoft IE11 browser is NOT supported in this version of Sentinet for the Developer Portal).
Customizing Developer Portal appearance and branding its content is described in the User Guide.
API Products
An API Product is a collection of one or more virtual APIs (Services) that are made available for external API Consumers (a.k.a. "Developers"). Developer Portal provides User Experience for Developers to learn about API Products and APIs they consist of, get APIs' documentation, metadata and monitor Developers' usage of provider APIs in real-time and with historical analytics.
Note
As described in the previous chapters of this document, Sentinet Administrative Console provides the same (and more) capabilities. Developer Portal optional components allow services and APIs to be presented for external or internal API Consumers (“Developers”) in a special way, where Developers can see only a subset of APIs grouped by API Products with some additional Developer Portal-specific functions such as:
- Developer self-registration.
- Auto- and self-management of API Keys.
- Monitoring of only Developer’s own message exchanges
In this tutorial we will create one API Product that consists of just one API, VirtualOrderService created earlier (described in Designing Virtual REST APIs chapter).
Start Sentinet Administrative Console, open Developer Portal drop-down menu and select Products menu option. Developer Portal drop-down allows Sentinet Administrators to manage all Developer Portal-related entities, even though typically only API Products and Subscription approvals are managed from the Sentinet Administrative Console.
Click + ADD PRODUCT button.
Expand Virtual Service group element and drag-and-drop Version 1 of the VirtualOrderService on the Service Version table (as an alternative way to assign virtual service(s) to an API Product, you can also use + Add button above this table to add virtual service(s) to this table). Name your API Product Order Product, give it some Description, click Promote button to promote API Product to Active state and click SAVE button to save this product.
Note that by default this API Product is publicly visible (not a Private API Product), it does not require explicit Subscription, and as a result, Approval for Subscription is not required either.
You can also notice that by default Version 1 of the VirtualOrderService was created (in Designing Virtual REST APIs chapter) with no API Key Required flag.
This particular default configuration allows Order Product and its APIs be used either with, or without API Keys.
Note
If API Key is not used by the users of the Developer Portal, then they will not be able to see their monitoring data (only Sentinet Administrative Console users will be able to see it).
Typically, API Products are created to require Subscription (and hence to require API Keys) and with required Approval of Subscriptions. All these settings can be changed at any time for virtual services and API Products.
Start new browser tab with the address of the Developer Portal, for example: https://myserver/SentinetDevPortal
Developer Portal Home page shows all publicly visible API Products as Product cards. User can drill down to a specific API Product or select API Products menu option to see all Products with optional view of API Products and their API as a tree view.
Note, that at this point there is no logged in user of the Developer Portal and yet, browsing through publicly visible APIs, API details and documentation are available:
Consumer Accounts and Users
At any point a user can Sign Up for the Developer Portal usage. When user signs up, a new Consumer account (Company name field) is automatically created with the signed-up user being its first Administrator. Self-registration Sign Up process will be completed once a user receives confirmation email with temporary password. If email server was never configured (step 6 of the Repository Web Application's configuration process) then users will not be able to complete self-registration process, and the only way to create Consumer accounts and its users will be to do it from the Sentinet Administrative Console by the Administrative Console users. In this tutorial we will assume email server is not configured (you can try complete self-registration process by executing step 6 of the Repository Web Application's configuration process with any valid email server and email account for outgoing emails).
To add a new Consumer account and Developer Portal user from Administrative Console, select Developer Portal -> Consumers menu option.
Then click + ADD CONSUMER toolbar button.
Enter Consumer Name (for example, Contoso Bank) and optional Description, click SAVE button.
Now switch to USERS tab where Sentinet Administrators can add, delete or modify Developer Portal users of a Consumer account.
Click + ADD USER toolbar button and on New User screen enter user Full Name, Email and change Access Rights to Administrator.
Click + Add button and follow to Add Identity wizard pages to add Username/Password type of identity. Click SAVE button after identity is added.
Subscriptions
Switch to the Developer Portal Web Application and use John Smith's login credentials to Log in into the Developer Portal. Once you are logged in, you can request Subscription for any API Product available in the Developer Portal.
New subscription, Order Product Subscription is created. You can modify subscription name by clicking Rename button:
In this tutorial we exercise simplified use case scenario when API Product, Order Product was created with no subscription required by the Sentinet Administrative Console. The API newly created subscription is immediately placed in Active state. Most typically, subscriptions and subscription approvals are required, in which case newly created subscriptions will be shown in Requested state until they are approved by Sentinet Administrator(s).
Without required subscription VirtualOrderService API can be called even if we did not create subscription above. If you try to make a call (for example, from your browser: http://myserver/Node/order.svc/getstatus?orderId=123) the call will succeed, but the logged in Developer Portal user jsmith will not see any monitoring or dashboard analytics data because nothing in this call identifies a Consumer account. If you do have subscription (that we created above) you may request an API Key(s) that will identify your calls, and by sending API Key(s) you will be able to see your own monitoring data. Moreover, if you change API Product's Order Product property to Require Subscription, calls without ApiKey query parameter or ApiKey HTTP header will fail (either query parameter or HTTP header must be present in this case).
Let's check what happens when we do send API Key without Subscription Required. Select Applications tab and click Add Application button.
An Application is a logical entity that may have one or two (secondary) API Key(s). Think of an Application as a named alias to your API Key(s). As a consumer of APIs, you may have a requirement to differentiate (for example, for analytical purposes) how your own calling "applications" use the same provider's API. Name your application (give API Keys ab alias, for example My Application), and click Save button.
You can now see in clear text auto-generated API Key, and you copy it to the clipboard.
Use this API Key as an ApiKey query parameter to make a call from the browser (for example: http://myserver/Node/order.svc/getstatus?orderId=123?ApiKey=IYpEnBflSdAdeMJDkoIvgGZPbLqUgl90tZ81LjwxNMXGF-Yc52HkQxoWTakiVXd7)
This time if you switch to the Monitoring tab, you can see your messages in real-time and historical logs:
Now let's check what happens when subscription is required and API Key is not provided. Switch to Sentinet Administrative Console, select Developer Portal top-level drop-down menu with Product menu option and click on Order Product to modify its Subscription Required property. Click SAVE toolbar button.
You will see Confirmation dialog box that suggests to automatically change API Key Required property of the VirtualOrderService to be turned ON. API Products that require subscription must have all APIs (that are part of this product) to be configured with API Required property turned ON.
If you confirm automatic changes of this API's property and review virtual service version after that, you will see this property turned ON:
Now, try to send request from the browser without ApiKey query parameter (for example, http://myserver/Node/order.svc/getstatus?orderId=123). You will now see that the call fails with HTTP 403 Forbidden and error message that states that API Key was not provided. Developer Portal user jsmith will not see this error (nothing identifies this call as "his" call), but from Sentinet Administrative Console users can see monitoring with all the details:
