Apigee recommends that you apply the best practices described in the following sections when building your portal.
Engage your audience
Add content that engages your audience visually and compels them to want to learn more. Enable API consumers to explore a portion of your portal without logging in. Provide self-service registration so they can get up and running quickly to build apps using your APIs.
Let users try your APIs
Auto-generate interactive API documentation from your OpenAPI Specifications to enable users to:
Provide use case examples and tutorials that are relevant to your audience and based on their level of experience. Demonstrate by example, such as a simple curl command sequence, or step through a more elaborate procedure.
Implement search engine optimization (SEO)
Ensure your content is searchable. Invest in SEO that improves your ranking in search results and enable users to find your content.
Create easy-to-understand, human-readable URLs. Define a user-friendly page URL when adding pages to your portal, as described in Creating a page.
Conveys the purpose of the page in a human-readable form.
Full or partial keyword matching in the page URL improves search ranking.
Typically, URLs appear in search results.
Provide a descriptive portal name
Define a unique and descriptive portal name for your portal, as described in Managing your portals. This content is used to populate the <title> tag for the home page (index) of your portal.
Full or partial keyword matching in the title improves search ranking.
Typically, the contents of your page titles are displayed as the first line of the search results.
Make your site easy to navigate
Define a navigation structure that makes logical sense, as described in Setting up navigation.
Keeps users oriented.
Helps users locate the content that they want quickly and easily.
Use a good mix of keyword phrases throughout content
Include keywords in your content when it is relevant and makes sense to do so. Prominence of a keyword string on your page can improve page ranking in search results. Try to predict the keyword strings users might use when searching for your content. Be cautious not to keyword stuff, that is, overuse keywords for the sole purpose of improving search ranking. This may result in your site being penalized by search engines.
Users searching for content will be more likely to get relevant hits.
Build a developer community
Employ social media to promote your API community through standard social channels, such as Facebook, Twitter, and so on. Publish blogs and forums that foster communication and interaction among the developers in your API community.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis page outlines best practices for building an engaging and effective developer portal using Apigee and Apigee hybrid.\u003c/p\u003e\n"],["\u003cp\u003eCreating user-friendly URLs, descriptive portal names, and intuitive navigation are crucial for enhancing searchability and user experience.\u003c/p\u003e\n"],["\u003cp\u003eEnabling interactive API documentation with live request and response capabilities allows users to quickly understand and test your APIs.\u003c/p\u003e\n"],["\u003cp\u003eIncorporating relevant content like tutorials and use case examples, that are based on various audience levels will improve the user experience.\u003c/p\u003e\n"],["\u003cp\u003eUtilizing social media and community features such as forums and blogs will help to build a stronger developer community.\u003c/p\u003e\n"]]],[],null,["# Best practices for building your portal\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n\u003cbr /\u003e\n\nApigee recommends that you apply the best practices described in the following sections when building your portal.\n\nEngage your audience\n--------------------\n\nAdd content that engages your audience visually and compels them to want to learn more. Enable API consumers to explore a portion of your portal without logging in. Provide self-service registration so they can get up and running quickly to build apps using your APIs.\n\nLet users try your APIs\n-----------------------\n\nAuto-generate interactive API documentation from your OpenAPI Specifications to enable users to:\n\n- Learn about the API\n- Send a live request to the API\n- View a live response returned from the API\n\n For more information, see [Publishing your APIs](/apigee/docs/api-platform/publish/portal/publish-apis).\n\nAddress primary learning paths\n------------------------------\n\nProvide use case examples and tutorials that are relevant to your audience and based on their level of experience. Demonstrate by example, such as a simple curl command sequence, or step through a more elaborate procedure.\n| You can learn from your internal consumers. Perform usability tests with internal consumers and revise content based on their feedback.\n\nImplement search engine optimization (SEO)\n------------------------------------------\n\nEnsure your content is searchable. Invest in SEO that improves your ranking in search results and enable users to find your content.\n\nUse the following best practices when structuring your content. For more information and additional guidelines from Google, see the [Google Search Engine Optimization Starter Guide](http://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf).\n\nBuild a developer community\n---------------------------\n\nEmploy social media to promote your API community through standard social channels, such as Facebook, Twitter, and so on. Publish blogs and forums that foster communication and interaction among the developers in your API community."]]
