azure / api-management-developer-portal

Developer portal provided by the Azure API Management service.

Azure API Management developer portal

This repository is managed by the Microsoft Azure API Management team and contains the source code of the developer portal. Refer to the official Azure documentation for more information and instructions.

Releases

The master branch of this repository is used for daily development purposes and may contain unstable version of the software. We recommend using releases for setting up your portal.

Interactions

You can report bugs or submit feature requests in the repository's Issues section.

Microsoft Azure Support assistance is limited to managed portals and only the initial setup of self-hosted portals (documentation); best effort support is provided for problems that are caused by environmental factors, such as (but not limited to): hosting platform, development environment, network configuration. Other self-hosted portal assistance requests (for example, problem with custom widgets) should be submitted on Stack Overflow with the azure-api-management tag. We don't provide support through GitHub Issues.

We welcome and appreciate community contributions.

License

The developer portal is published under the MIT license.

api-management-developer-portal's Issues

Edit Widget does not work

I am trying to edit the Product List widget to group the products according to their naming convention.
Error message : "No component name specified".

To Reproduce
Steps to reproduce the behavior:

1. Go to the product page
2. Click on 'Edit widget'
3. See error
   

Expected behavior
Being able to edit the way the objects (api, products, etc...) are displayed

Desktop (please complete the following information):

• Chrome 72.0.3626

Confusing API dropdowns styling

Describe the bug
In the page for OpenAPI specification, the contents do not display correctly, and the headings of the definitions are not readable. There are numerous headings and sections which should not be displayed in the customer's opinion.

Expected behavior
Could you please help to modify the layout of the page and change the definition headings to be more readable?

Thank you very much.
Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Win 10
• Browser Chrome

Oauth2 authentication on the developer portal

Is your feature request related to a problem? Please describe.
The developer portal only allows username/password authentication, while we have Okta as identity provider.

Describe the solution you'd like

Ability to use Okta as authentication for the developer portal, with authorization based on scopes (and other claims)

Cleanup script should revert all actions of the generate.bat (including storage upload)

Link to update post broken

Describe the bug
The README's link to the update post (https://docs.microsoft.com/en-gb/azure/api-management/api-management-howto-developer-portal) is broken

To Reproduce
Click it

Expected behavior
Update post shown

Desktop (please complete the following information):

• OS: Win 10
• Chrome

Step 3 in the documentation

Under this section:

connection_string is the connection string to the storage account, which will host media files.

There is a Connectionstring in the SAS page, if you use that there will be an error in the upload because the signature cannot be Url Encoded.

The Connectionstring under "Access Keys" is not Url Encoded. Perhaps you should make sure the text in the is clear on what connection string to use.

Watching the video playback was much better in this regard.

Show non-product subscriptions in user's profile page

Is your feature request related to a problem? Please describe.
When attaching a user to an api-specific subscription, the only way to get the subscription key is through the azure portal. Shouldn't the subscriptions show up in the user's profile?

Describe the solution you'd like
I'd like to see a subscription that is not attached to a product show up in the user's profile.

Files on blob storage widget

Is your feature request related to a problem? Please describe.
Having a widget to display documents contained in a specific blob container

Describe the solution you'd like
Even we are in the age of WIKIs, customers still love PDF documents and Excel files to describe procedures, complex data structures and more.
It would be nice to have a widget that can used at different scopes:

• Global public: all users (authenticated and not authenticated)
• Global for authenticated users only.
• Products (for every products a container named as the product is created)
• Api (for every APIs, a container named as the API is created )

Describe alternatives you've considered
As today we configured something like this adding client side javascript to call an api on top of the strage account. I’d prefer have a server side call.

Cross-browser compatibility

In the step 4 of link self-hosting-the-portal it is mentioned that "Currently, the portal works only in the Google Chrome browser."

When will the APIM be available with cross brower compatibility? Can you please share some timeframe?

How to expose Microsoft developer portal API

Hi,
I am looking for some document, which defines how to expose the azure developer portal API call's?
For e.g, In my storage account, there are some files or blobs which i want to display into my customized developer portal. How to get the file service or blob services APIs expose information so we can hit them and get the required information.

Pagination in API Operation

In API page max 20 operations can be list out and will not show if we have more than 20 operations, then we are not seeing any pagination for Page Contract.

Is there any way around or it will be published as new feature?

Sign in/up with AAD

Cannot run publish after new update

Describe the bug
I did a new pull and a totally clear setup this afternoon. I got the latest master branch and went thru all the steps, but I get an error when executing "npm run publish".

To Reproduce

1. Pull the new code (6de413d)
2. Go thru the steps in the wiki.
3. reach step 6.

Errorlog
0 info it worked if it ends with ok
1 verbose cli [ 'C:\Program Files\nodejs\node.exe',
1 verbose cli 'C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js',
1 verbose cli 'run',
1 verbose cli 'publish' ]
2 info using [email protected]
3 info using [email protected]
4 verbose run-script [ 'prepublish', 'publish', 'postpublish' ]
5 info lifecycle [email protected]prepublish: [email protected]
6 info lifecycle [email protected]publish: [email protected]
7 verbose lifecycle [email protected]publish: unsafe-perm in lifecycle true
8 verbose lifecycle [email protected]publish: PATH: C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\node-gyp-bin;C:\Users\F2530228\source\repos\api-management-developer-portal\node_modules.bin;C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\wbin;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0;C:\Windows\System32\OpenSSH;C:\Program Files\dotnet;C:\Program Files (x86)\Microsoft SQL Server\Client SDK\ODBC\130\Tools\Binn;C:\Program Files (x86)\Microsoft SQL Server\140\Tools\Binn;C:\Program Files (x86)\Microsoft SQL Server\140\DTS\Binn;C:\Program Files (x86)\Microsoft SQL Server\140\Tools\Binn\ManagementStudio;C:\Program Files\Microsoft SQL Server\130\Tools\Binn;C:\Program Files\nodejs;C:\Program Files\Git\cmd;C:\Users\F2530228\AppData\Local\Microsoft\WindowsApps;;C:\Users\F2530228.dotnet\tools;C:\Users\F2530228\AppData\Roaming\npm;C:\Users\F2530228\AppData\Local\Programs\Microsoft VS Code\bin
9 verbose lifecycle [email protected]publish: CWD: C:\Users\F2530228\source\repos\api-management-developer-portal
10 silly lifecycle [email protected]publish: Args: [ '/d /s /c',
10 silly lifecycle 'npm run build-publisher && node ./dist/publisher/index.js' ]
11 silly lifecycle [email protected]publish: Returned: code: 1 signal: null
12 info lifecycle [email protected]publish: Failed to exec publish script
13 verbose stack Error: [email protected] publish: npm run build-publisher && node ./dist/publisher/index.js
13 verbose stack Exit status 1
13 verbose stack at EventEmitter. (C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\index.js:301:16)
13 verbose stack at EventEmitter.emit (events.js:189:13)
13 verbose stack at ChildProcess. (C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\lib\spawn.js:55:14)
13 verbose stack at ChildProcess.emit (events.js:189:13)
13 verbose stack at maybeClose (internal/child_process.js:970:16)
13 verbose stack at Process.ChildProcess._handle.onexit (internal/child_process.js:259:5)
14 verbose pkgid [email protected]
15 verbose cwd C:\Users\F2530228\source\repos\api-management-developer-portal\scripts
16 verbose Windows_NT 10.0.17763
17 verbose argv "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "run" "publish"
18 verbose node v10.15.2
19 verbose npm v6.4.1
20 error code ELIFECYCLE
21 error errno 1
22 error [email protected] publish: npm run build-publisher && node ./dist/publisher/index.js
22 error Exit status 1
23 error Failed at the [email protected] publish script.
23 error This is probably not a problem with npm. There is likely additional logging output above.
24 verbose exit [ 1, true ]

Desktop (please complete the following information):

• OS: win10
• VS code

Cross-browser support, incl. ad blockers

Store a subscription friendly name

Is your feature request related to a problem? Please describe.
When a product allows more than 1 subscription per user, a user can request multiple subscription, but there is no way to identify each subscription other than the subscription id.
Allowing to store a friendly name, users can see each subscription and the get the key for each one of the subscription they registered for.

This is especially useful when we set different policy configuration for each subscription.

Describe the solution you'd like
To have a field associated with each subscription called "Friendly Name" or "Description" for users and administrators to be able to distinguish 2 subscriptions for the same { User, Product }.

Describe alternatives you've considered
N/A

Additional context
We will setup throttle policies per subscription with specific values for each one.
After the user creates the subscription, and the administrator creates the policies, users of the dev portal cannot easily identify which subscription is which.

New subscription that requires approval previously created and deleted don't request admin approval

Describe the bug
When a product with "Requires approval" approves a subscription for { product, user }; if the submission is deleted and the user requests it again for the same { product, user }, the approval is not required and the user gets the subscription without admin approval.

To Reproduce
Steps to reproduce the behavior:

1. Create a subscription request for a user and product
2. Admin approves the subscription
3. Admin deletes the subscription without cancelling or suspending the subscription
4. User requests subscription to the same product as done in number 1.

Expected behavior
The subscription requires admin approval before being active.
Since the admin deleted the subscription, this means the access to the product needs to be prohibited; the user can get access again without admin consent in this case.

Screenshots
NA

Desktop (please complete the following information):
Not os/browser specific

Smartphone (please complete the following information):
Not os/browser specific

Additional context
The product needs to have "Requires approval"

paperbit runtime error on Local development

Describe the bug
After compilation pages do not load successfully (local development). Just for more specific, I am facing this issue from last two days before that it was working fine.

Adding console log
localhost-1559900938157.log

OAuth/OpenId setup in Developer Portal

If We have done OAuth/OpenId setup for an API, then Authorization header has been auto-populated in Developer Portal during testing once we select authentication option.

But in New Portal, There is no Authorization Header implemented, that means no OAUTH or external authentication can be used with operations.

Unable to publish after getting code March 15

Describe the bug
When trying to publish (NPM publish at the terminal command line), I get this error: 401 Unauthorized - PUT https://registry.npmjs.org/apim-developer-portal - You must be logged in to publish packages.

To Reproduce
Steps to reproduce the behavior:
I threw away all the code, got it all again from your repository, did npm install, npm start and the npm publish.

Log
Located here:
https://enfo-my.sharepoint.com/:u:/g/personal/mikael_sand_enfo_se/ETqrfWKMxSJKqoNbZooPPjoBvxxOtHol-EFAsM88UfXeNg?e=KHqSbe

API / Product deprecation

How to mark exposed APIs or Product as deprecated in API management. Right now i could see the only option to update the descriptions.
Including deprecated flag in swagger does not work. Is there any better way available to mark exposed entities as deprecated?

How to efficiently deprecate an API and announce to consumers?

Cannot publish site with new images.

Describe the bug
Image files become XML-files with errors after publish.

To Reproduce
I follow the how to guide to create a new design. I upload new pictures, I leave the site running and run the npm run publish. This seems to pull image files from blob storage and store them in the website/content folder. The files become 1 kb large jpgs.
I opened the jpgs in VS and saw that they are xml files, containing errors.

<?xml version="1.0" encoding="utf-8"?><Error><Code>ResourceNotFound</Code><Message>The specified resource does not exist. RequestId:c87ba921-701e-0036-1776-d259a6000000 Time:2019-03-04T10:39:08.2825033Z</Message></Error>

Expected behavior
Files should be jpegs.

Screenshots
I also have the run log from chrome showing som additional information from when I added a new image to the site:

Additional context
Basically it seems it cannot get the file from blob storage when the publish script runs.

Deployment strategy - questions

What is the recommended approach for deploying the development portal? We are having the following issues (in general for APIM deployment):

• git repo includes swagger json (not reference to swagger json) so it overwrites pipeline changes. i.e. if we save to repo, deploy API code, and then deploy repo back to APIM, all swagger changes are overwritten

• as such, can't use the repo to deploy the developer portal (or will overwrite changes from pipeline).

• the only solution I can see is to save to repo, update swagger json manually to what was deployed, then re-deploy in each environment?

What is the suggested approach to deploy portal changes through environments?

Documentation: content migration between environments

Document how to run the migrate.bat script.

Page editing carrying over to all pages

Describe the bug
Created a new page. Edited content on new page. It ended up deleting all content on the rest of my pages and turning every page into the page I had edited. See video:
https://www.screencast.com/t/6fYer8mKLD

To Reproduce
Steps to reproduce the behavior:

1. Create new page
2. Edit content in new page
3. Click existing page
4. Confirm that content of existing pages was overwritten by new pages

Expected behavior
Pages edit separately and don't overwrite.

Screenshots
Video: https://www.screencast.com/t/6fYer8mKLD

Desktop (please complete the following information):

• OS: Windows
• Browser - Chrome
• Version 75

Unable to access Static Web site after publish

Describe the bug
The site is built/published locally. I then send the files to blob storage to expose it using static web site.
I get really nasty errors when accessing the site:

Can’t connect securely to this page
This might be because the site uses outdated or unsafe TLS security settings. If this keeps happening, try contacting the website’s owner.

If I turn off forced HTTPs on the blob storage, and access the site using http, the local company proxy stops me because it thinks I am accessing a spam site...

I have tried both edge and Chrome for this.

Additional context
Perhaps you should consider publishing to something else or include instructions on how to use https with static websites.

Enums are not rendered in API object model

Describe the bug
Enums are not rendered on the page

To Reproduce
Steps to reproduce the behavior:

1. Go to sample_openapi_json.txt and create a blank api from this JSON.
2. Launch the developer portal and Click on the api name
3. Object rendering is incorrect

Expected behavior

1. The enum values should have been rendered.
2. I notice a small box , is that by design?

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• Browser :chrome
• Version :Version 73.0.3683.103

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

A wizard for non web people

I love the new portal and I love the freedom I have to design the portal so that it looks more "me". However I think a lot of users might find the design experience a bit too much.

Perhaps you could add a wizard, or a couple of templates that are configurable.

1. Choose a layout.
2. Choose colors (or skip)
3. Upload images, logo and such (or skip).
4. Fill in some basic information (company name etc).
5. Boom! Site created!

Community: "Issues" functionality not available

If you have questions, comments, or concerns related to Issues not being available in the new portal, please post them here.

Legacy portal deprecation

If you have questions, comments, or concerns related to deprecation of the old developer portal, please post them here.

---

Aggregate:

1. Concerns around a possibility of breaking existing DevOps pipelines
2. Disabling the old portal in API Management service
3. VNET configuration changes

Old vs new developer portal - questions

**Query-Help **
We have below query with New and Old developer portal:

1. Are we are planning to remove old developer and Publisher portal?
2. Where we can find feature wise comparison document?
3. Are you have plan to implement all functionality which we have in old developer portal? Do you have any plan release date with all old developer feature?

Testimonials widget does not work

Every time I try to change the text I get a lot of errors saying:

Ability to embed HTML/JS on non-self hosted dev portal

I'd like to embed certain items such as a "Run in postman" button for our postman collection but I am not sure how one would go about doing that when the portal is not self hosted. Is it possible?

Improve authentication error messages

It is not always clear why authentication fails for users in both development and production modes.

There is plenty of room for improvement of debugging experience. Thus, when authentication fails we could do several things:

• handle 401 response as normal application state and prevent the whole error stack to be dumped to console;
• check token format expiration date/time and relay it to the user/developer;
• check configuration sufficiency on application startup and notify what's missing or misformed.

Switch to ARM contracts

Portal needs to use ARM-compatible contracts, which are the only contracts supported by the management API version 2019-01-01 (and later).

This change would also clear ground for enabling RBAC for content management.

How to self host developer portal in local environment for APIM whose domain name is other than managment.azure-api.net

We are trying to configure our local environment for a APIM whose managementApiUrl is https://testportal.xyz.com instead of "https://testportal.management.azure-api.net".
You can see that the domain name of our testportal is xyz.com and not management.azure-api.net.

We are getting below error log for testportal having domain type other than management.azure-api.net.

"https://testportal.xyz.com
_(node:13328) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token < in JSON at position 2
at JSON.parse ()
at IncomingMessage. (C:\Users\anju.c.sharma\azure_devportal\api-management-developer-portal\scripts\generate.js:35:34)
at IncomingMessage.emit (events.js:205:15)
at endReadableNT (stream_readable.js:1154:12)
at processTicksAndRejections (internal/process/task_queues.js:84:9)
(node:13328) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:13328) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code."

Also the code which is there at generate.js:35:34 is as below
resolve(JSON.parse(data));

Please help us to resolve this on priority if it a bug or let us know the way in which this can be achieved if this type of functionality is already implemented?
Also , let us know if you need more details as well.

Update VNet troubleshooting guide to reflect endpoints required for developer portal

Common Network Configuration Issues

Sign In through Azure AD account (oauth authentication).

Is your feature request related to a problem? Please describe.

Provide feature to validate user through Azure Active directory account.

For Azure active directory user don't want to go with Sign Up process.

Looking for old developer Functionality into new developer portal, with some extra feature.

Can you please let us know, when we are getting below functionality of old developer portal into the new one.

1. We are looking for Blogs feature implementation. Also, will the feature now support blobs categorization and based category filtration in new azure developer portal?
2. We are looking for complete Media library Feature implementation.
3. We are looking for Content feature implementation. Also, will the feature now support content categorization and based category filtration in new azure developer portal?
4. We are looking for APIs filtration based on Tag implementation.

Couldn't find Application menu in new developer portal (preview)

We are using the "Application" feature in the old developer portal. I couldn't find "Application" functionality in the new developer portal(preview)

Is that functionality is no more supported? If not supported what could be the alternative solution?

It will be great if all the existing features also available in the new portal.

Not able to connect to different domain name APIM

Hi, we are not able to connect to different domain name than azure-api.net. And getting ETIMEDOUT error.

I have followed all the config steps, let me know if need to do some other changes as well.

Step 7 in the documentation

I am not a programmer (any more) and therefore I might be a good fit for some people that wants to provide feedback.

The text refers back to earlier steps for what to put in and , there are no real values above to refer to. Perhaps you should say:

is the name of the storage account you specified in the ./src/config.publish.json file.

About account key:
is the key for the storage account not the ConnectionString or SAS key used earlier, but the access key. At least that is how I got it to work.
[Edit] Looking at the Video, this was not a problem.
I hope you find this helpful.

Can't add a custom Product: Subscribe form

Describe the bug
Unable to generate Apim-Subcription-Key to access API,

To Reproduce
Steps to reproduce the behavior:

1. Go to New APIM developer Portal
2. Click on Product Manu

Product and API is listed but unable to find any subscribe option to subscribe available product.

Expected behavior
Require subscribe option to generate APIM subscription key.

Screenshots

Desktop (please complete the following information):

• OS: Window
• Browser : Chrome

Not able to run Developer portal

I am able to successfully execute https://github.com/Azure/api-management-developer-portal/wiki/self-hosting-the-portal till step 3. Also, when i run npm start, the build gets complied successfully, however, due to some issues it is not running on the browser.

Build Succeeded:

Not running on Google Chrome:

Please help me with this.

Note: The same configuration is working on another machine but on my system it is not working.

Dynamic menu for anonymous vs signed in users

The developer portal renders the same UI for anonymous and signed in users which is very confusing.

I wasn't expecting to see a "Profile" navigation item when not signed in.
Conversely, when signed in, the navigation bar should not display the "sign up" / "sign in" items and the "Sign up" button on the home page could be hidden.

Is this possible today? What am I missing?

Thank you.

Indicate subscription status (e.g., pending approval, approved, rejected etc.)

Describe the bug
If a user requests a subscription and it hasn't been approved, the user can request it over and over creating new requests in the backend. Not sure how the current portal works, but if a subscription exists for the user in the "Submitted" state, portal should not allow the user to request again.

To Reproduce
Steps to reproduce the behavior:

1. Request subscription to a product
2. The subscription is created in APIM backend as "Submitted" state
3. Navigate back to the product page

Expected behavior
The "Add subsctiption" button should not be shown, since one is in submitted state.

Screenshots

Desktop (please complete the following information):
No specific to OS/browser.

Smartphone (please complete the following information):
No specific to OS/browser.

Additional context
The product needs to have the "Requires approval" option enabled.

Documentation: authentication with a custom server

Widget editor - List of APIs

Please let us know the timeframe by when we can get this feature?

CORS Issue with new portal

When we were trying to call any API from new management portal we were getting below CORS Issue.

"Unable to complete request
Since the browser initiates the request, it requires Cross-Origin Resource Sharing (CORS) enabled on the server."

URL encoding for query parameters in the interactive console

Describe the bug
When supplying input parameters for API methods - we should URL-encode the values before invoking the method. This matches the behavior present in Swagger UX.

To Reproduce
Steps to reproduce the behavior:

1. Click an API Method
2. Click Try It
3. Provide an input field with characters that need escaped (e.g. \, etc.)

Swagger UX

Expected behavior

Screenshots

APIM UX

Additional context
This behavior was broken in previous DEV portal - hoping we can improve this for Portal vNext!

How to self-host developer portal on consumption tier?

The guide on https://github.com/Azure/api-management-developer-portal/wiki/Self-hosting-the-at step 2: Configure talks about

"Enable the direct REST API access to your API Management instance. Copy the generated token and place it in the "managementApiAccessToken": "SharedAccessSignature ..."

Except this doesn't seem to be possible with the consumption tier. Is there an other way to self host the developer portal with the consumption tier?