Product Configuration

1. Overview
2. Quick Start
3. Configuring the portal
4. Configuring plans
5. Configuring your service
6. Configuring your DNS
7. Advanced Kung Fu

1. Overview
   Your API connects and communicate seamlessly with 3scale’s infrastructure via the integration of the 3scale API that you can find here or via the integration of one of our language specific Plug-in that you can find here.
   The Management control panel then lets you configure all the aspects of the look and feel of your site and its domain name as well as the definition and setting-up of your API subscription plans.
   Controls are split into the following areas:
   • OPERATIONS:
     • the Dashboard gives you an overview of how your service is running, with number of users signed up and status information.
     • the Messages tab controls communication with your users.
     • the Forum tab gives you access to the forum available on your developer portal and post new topics, answers to questions, etc.

   
   

   • USERS:
     • the Overview summarizes the latest sign-ups to your API subscriptions plans.
     • the Search lists users who’ve signed up to use your API and allows you to manage individual accounts.

   
   

   • STATS:
     • provides you with a detailed view of the usage done of your API according to the various metrics you’ve defined.

   
   

   • FINANCE:
     • this tab is only active if you have the Billing & Payments module enabled. It provides you with a breakdown by month and user of the amounts to be invoiced for the usage of your API.

   
   

   • API:
     • the Overview http://www.3scale.net/admin/service tab enables you to activate or deactivate the Documentation Wiki, App. Galery and Forum features of your developer portal.
     • the other tabs enables you to access and manage the different elements of content of your developer portal such as the Wiki, the Welcome page, etc…
     • the Plans http://www.3scale.net/admin/plans area gives you access to the creation of your different API subscription plans and the setting-up of usage limits, features and pricing rules based on your own metrics and criteria.
     • the Test http://www.3scale.net/admin/test area provides with the elements to test the integration of your API with the 3scale infrastructure.

   
   

   • SITE:
     • for a fast and easy setting-up of the look and feel of your developer portal you shall go to the Colors tab.
     • for a full customization of your developer portal in line with your branding and customer experience you shall go to the Design tab.
     • the DNS enables you to manage the domain or sub-domain of your developer portal as well the public opening, or not, of the latter.

   If you can’t find what you need here, please contact us at support@3scale.net and we’ll get right back to you.

2. Quick Start
   This guide takes you through the minimal steps to launching your API portal and checks off the individual steps in the “go live” track on the admin panel.
   For more detail on any of the subjects covered here follow the links to the detailed help page.
   1. Complete account information
      In order to use the service we need complete contact details for the user and the organization running the service. You can fill these in here:
      • Here for organizational details
      • Here for user details.

      If you plan to offer paid access to your service, you’ll also need to fill out Payment Information.

   2. Configure your portal Look and Feel

      Once your portal is live, developers and partners willing to use you’re API services will be able to subscribe to one of your API subscription plan and create an account.
      But before going live you’ll want to tweak the look and feel as much as possible in order to fit it to your current site branding and layout.
      You can do this in the admin section of the site. Your configuration options include logos, colors, links and text in all areas of the site.
      The only mandatory change is to upload a logo, but you’ll likely want to do much more than that.
      See the Configuring the portal page for more information on how to set up look and feel.

   3. Get your service connected

      In order to manage sign-ups and track the usage done of your API, your API must be integrated connects with 3scale’s infrastructure via the integration of the 3scale API that you can find here or via the integration of one of our language specific Plug-in that you can find here.
      In order to set this up:

      • Check to see if there is already a Plug-in available for your language or platform.
      • Ensure your API is able to capture keys as one of the parameters for the operations you want to manage access to.
      • Once the Plug-in is installed, it should communicate directly with the 3scale backend services and begin registering traffic that you can check with the test service.
      • If you have problems with this step or have special requirements for connection, please don’t hesitate to contact us at support@3scale.net.

      The service connection step is complete once successful tests have been passed through the system.
      Also see the service configuration guide for an overview of the steps and check information on plan configuration to set limits and pricing rules for the service.

   4. Set your domain name

      You can run your portal on a 3scale sub-domain such as http://mycompany.3scale.net or under a sub-domain/domain of your own. In order to do this you need to:

      • Redirect a CNAME or A record from your domain registrar to 3scale’s servers – see here how do to do this.
      • Indicate the chosen sub-domain / domain in your account settings area.

      You can change the DNS location at any time in the future but beware that links already coming to your old domain location may then no longer be valid and confuse users.

   5. Go live

      Finally, when your entire configuration is done and your service is tested you can go live with two modes:

      • Private Mode: at any stage you can allow users of the API to see the portal in-situ and use it fully by distributing the site access code you set in the account settings area.
      • Public Mode: when you’re ready to open the site publicly you can take the final step and take the wrappers off by removing this code entirely, at which point your portal will be publicly visible.

      If you’re about to go live, let us know at support@3scale.net so we can help you promote the service and list you on our 3scale site.

3. Configure the portal
   Once you’ve set up your account, it’s time to set up your service information, and customize the look and feel of the site. You can do this by accessing the SITE tab.

   

   Within this area you can configure the Content to be shown and the Look and Feel of the your Developers and Partners Portal :

   • The link to your main web site
   • The favicon to be shown in the navigation bar
   • The google analytics tracking code
   • The text to be shown in the dashboard of your users when they log into their accounts
   • The logo to be shown in the header of the portal
   • The colors of the visual elements to be shown in the portal

   
   
   The Design and the Look & Feel of your Portal can be:

   • set-up fast and easily through the Colors sub-menu

   
   
   

   • fully customized with your branding and customer experience via the Liquid feature.

   

   
   
   In the Usage Rules sub-menu you can define the following:

   • Signup review policy: if you choose this option, you will be informed upon every signup for your web service, and users will not receive their key until you validate them.
   • Signup intended use specification: if you choose this option, users that sign up will be prompted to provide information on the intended use of your API.

   

   The Content of your Portal can be defined via the API menu:

   

   In the sub-menus, you can specify the following elements:

   • Activated and De-activate modules such as the App. Gallery or the Forum
   • General Service description: this appears on the front page of the portal.
   • API description: edited in the form of a simple wiki, the system allows you to add arbitrary pages and these automatically appear on the menu. Code markup information is provided in the edit window.
   • Contact and Support information: this information is shown when user clicks “support” in the footer of the page or elsewhere on the portal.
   • Featured information in the main page: small amount of content that appears in the inset box on the front page of the portal.
   • All data can be entered using html and by using html style clauses you can define your own styling. You can also upload assets to be referred across the descriptions.

   
   

4. Configure plans
   In the API menu, the Plans area gives you access to the creation of your different API subscription plans and the setting-up of usage limits, features and pricing rules based on your own metrics and criteria.

   

   You will then eventually publish these plans to make them available through your Developers and Partners Portal, as for example in the screenshot shown:

   

   You can create as many subscription plans as you want/need and for each of these plans you can define totally different pricing rules based on different sets of metrics and features.
   You can describe contracts for your service from the PLANS tab, providing the following information for each one:

   • Contract name: a short indicative name.
   • Legal Text: the legal text that users will have to agree to be permitted to contract the service.
   • Features: the name and a description of each Feature offered by the service. Features have an informational function to potential clients. A contract type can have every defined feature set as available or unavailable. According to the information provided, a comparative table will be automatically generated (an example of such a comparison table of “SSL Access” feature can be seen in Figure 3).
   • Metrics: a metric is a measure on a specific resource related with the provisioning of your service. There is no limitation on defining metrics, examples include: number of hits to a certain function of your API, amount of storage space used by your service to store data, amount of CPU time needed for the execution of a service call, etc. The interface allows you to define metrics by providing a name, a description and a unit (seconds, Mb, units, etc…). Usage values of are automatically reported to 3scale (see step 4), and our servers use this data for billing, limit checks, and plotting statistical data.
   • Fixed fees: You can set up a fixed price to be charged to your clients monthly, independently on the service usage.
   • Variable fees: You can set up pricing rules dependent on the usage of the service. Your clients will automatically be billed on a monthly basis according to the rules you specify. There are different pricing rules available to express different needs. Figure 4 shows the interface that captures the specification of a pricing rule on a metric called Hits. The rule captures the range of values for which a specified unit price applies. In the case of this example, the rule specifies a 0.5€ cost per hit, when the number of hits in a month are between 1000 and 5000. Rules can be combined such that different prices can be assigned to different ranges of values.

   

   • Usage limits: You can also specify the usage limits for a specific contract by setting up limiting rules. There is one single type of limiting rule, which is a maximum threshold limit by time. You can specify a maximum threshold to one or more of the defined metrics by setting up the maximum value and the time frame over which the system will control that the usage is below the specified limits. As in the case of pricing rules, usage limit rules can be combined.

   




5. Connect your service
   To let 3scale handle identity authentication, usage limits, and the budget availability of the user, your service needs to connect to 3scale to signal a transaction start upon reception of a request in your API. Once, a transaction is complete the confirming the usage carried out to 3scale. If something goes wrong during the service processing, or the user cancels the operation, your service communicates this to 3scale cancelling the ongoing transaction. To communicate the three named events (start, confirmation, and cancelling) to 3scale, you can use one of three mechanisms:
   • Connecting to the 3scale backend through the 3scale raw API. 3scale offers a very simple API for the three named events. Inserting the REST calls into your service code and handling the responses is easy, and you can have total control on the process.
   • Connecting using Plug-ins. From the 3scale web site you can download a library (Plug-in) written in the same programming language as your web service. This Plug-in encapsulates the REST call to the 3scale backend, offering a simpler interface to be integrated into your service code.
   • Custom connection. If your service has specific connectivity requirements, or you require a communication protocol that the current 3scale API cannot implement, contact us, and we will do what we can to get you connected.

   
   
   The communication mechanism is based on the use of different keys to identify and validate the identities of service users and providers:

   • Provider Authentication Key: This key identifies the Web Service provider towards the 3scale backend. Each Connect account has this key associated and available from the administration Dashboard. The key needs to be passed as a parameter in every call from the service to the 3scale backend.
   • Provider Response Key: In order to let the users validate the authenticity of the response, a key validation mechanism can be used (not mandatory). The mechanism consists on appending a key with every API response. This key is shared between API user and API provider, and by checking the correspondence, the user can validate if the response comes from the provider. Each Connect account has a public different key associated with it for each different user of the API. This key is available from the USERS menu on each contract summary.
   • User key: API users append their unique user keys in each one of their calls. This key identifies them to the service. 3scale generates these keys and issues them to users when they sign up. The system also offers an API that can be called by your web service to authenticate users and keys.

   
   
   3scale API
   Communication between your service and the 3scale backend happens via the 3scale API that mediates all authentication and reporting calls. Check out the API documentation here.
   
   
   Plugins
   To make integration easier, 3scale offers libraries (Plug-ins) that encapsulates the communication actions with 3scale, taking complete control of the data connection, data encryption, and data caching to ensure reliability and performance. Check out the Plug-ins available here.




6. Configure DNS
   3scale allows you to direct an external sub-domain or domain to your developer portal to integrate your API presence with your existing site. You can do this using the DNS control in the SITE menu.

   

   You need to enter the full sub-domain but without pre-pending the protocol, i.e. if you want “http://api.mydomain.com”, then add “api.mydomain.com” and not “http://api.mydomain.com” or “api”.
   
   
   Once this setting is made you’ll need to adjust your DNS records to create a record pointing to our servers. The normal way to do this is to create a new CNAME record pointing to the domain dns.3scale.net. The instructions vary depending on your registry provider (see below for some common examples).
   If you need to redirect a full domain (www.mynewapi.com) then you’ll most likely to add an A record instead in which case contact us at support@3scale.net for the required configuration details.
   
   
   If you have problems with this please contact support@3scale.net.
   
   
   Domain redirection with GoDaddy
   To set up a new CNAME with GoDaddy you need to carry out the following steps:
   Log in to your GoDaddy account.

   • Open the Domains tab and select “My Domain Names”.
   • Click the domain that you want to redirect from.
   • Click the option “Total DNS Control And MX Records”.
   • Click “Add New CNAME Record” at the top right of the box labeled CNAMES (aliases).
   • For the “Name” item, enter only the sub-domain of the address you want to use. For example, if you are redirecting from www.mydomain.com and want to redirect “developers.mydomain.com” to 3scale then just add “developers” here.
   • For the “Host Name” name field enter “dns.3scale.net” to direct to our servers. Specify a TTL of 1 hour.
   • Click OK.
   • This completes the redirect and you can log out of GoDaddy. Propagation of the DNS setting may take up to 24hrs, however it’s often operational in 15-30 minutes. If the domain isn’t available after 24hrs contact support for help.
   • Now, if you haven’t already done so, you need to set up your 3scale account to accept traffic from the sub-domain. To do this login to your 3scale account and go to the account area to change settings as described at the beginning of this section.

   If you need to set up an A record then this works as follows

   • First contact us at support to obtain the IP address to use with you account.
   • Within GoDaddy, instead of creating a CNAME instead click the Add A Record button.
   • Enter the @ symbol for the host. Then add the IP address we give you.

   
   
   Domain redirection with Register.com
   To set up a CNAME with Register.com, carry out the following steps:

   • Log in and go to the “Domain Manager” page. Click “Domain Alias” in the upper left corner of the page.
   • Click on the “Add Alias” function.
   • Type out the full domain you want to redirect, such as developers.mydomain.com. Then make enter dns.3scale.net as the target. Click the yes button to add the record.
   • The new entry should appear on the Alias summary screen.
   • Now you need to set up your 3scale account to accept traffic from the sub-domain. To do this login to your 3scale account and go to the account area to change settings as described at the beginning of this section.
   • The DNS changes could take up to 24hrs to propagate, however it is has not happened by then please contact us at support to check what might be wrong.

   
   
   Domain redirection with Yahoo
   If you’re using Yahoo, small business configuration works like this:

   • Log in to your Yahoo small business account.
   • Click on the “Domain Control Panel” below the domain you’d like to redirect.
   • Click “Manage Advanced DNS Settings”.
   • Click “Add Record”.

   In the Source field, enter the sub-domain you want to use (e.g. “developers” – and not “developers.mydomain.com”).

   • Enter dns.3scale.net in the Destination field.
   • Click Submit.

   This should complete the configuration and you can log out of Yahoo. The propagation can take up to 24hrs but may be complete in as little as 15-30 minutes. Once it’s complete you can carry out the settings mentioned above in the account area.
   
   
   If the settings are not active within 24hrs contact support to see if we can help with this.
   
   
   If you want to add an A record carry out the steps above, except:

   • First contact us at support to obtain the IP address to use with you account.
   • Within Yahoo, instead of creating a CNAME instead click the Add A Record button.
   • Leave the Source field blank. Then add the IP address we give you.

   
   

7. Advanced Kung Fu

   If you have problems not currently covered in this guide, don’t hesitate to contact support@3scale.net.