API Economy is taking off exponentially and its every business need to expose their digital services and assets in a secure way. I'll walkthrough in this article how one can take a API-first , design first approach to take into the account, the needs of API consumers and various steps that lead to creating a Developer Portal using all the tools that we've currently. Please note that these tools have alternatives in the market, but these are what got me to the goal post in the fastest way and case could differ for others.
Open API Specification
One of the broadly accepted industry standard for describing modern API's and programming language-agnostic are open API Specs. For the sake of this article I've taken JSON Resume Schema as a reference API to create a API end points for aspects of resume.
1. Stoplight - Gartner has recognized it as one of the cool products considering the fact that API design and API testing as important stages in full life cycle API management. Stoplight studio is a nice tool with visual interface for designing API pretty fast and if you are wondering how fast - you need to check out this video. Here is the output of stoplight generated openAPI YAML file.
2. SwaggerHub - To write a book, you would have probably read a lot of books, to write an amazing code, you would have probably read through a lot of code, so with API's to design a good API, you would have been exposure to so many API designs. This is a nice place with collection of many published API designs and some other place similar would be postman API network. There are 2 ways to developing API's as in this article and the SwaggerHub has also the capability to generate Server Stubs which will provide a template server code that can be good enough to start writing the business logic and to put in the persistent layer for storing data. Github link for generated code.
3. Serverless - Open source serverless framework helps in deploying app in cloud platforms when we are able to get the function, event and resource configuration updated in the serverless.yml file. I got lambda functions coded in Node, express and using dynamoDB for persistence and the Github link for these.
4. API Gateway - Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. After the previous serverless deployment we've got the API Gateway in place and in case you are wondering if there is anything to be done here, you can move to the final step.
5. Dev Portal - Now that you've got your API's ready and deployed, this article explains the steps for setting up the dev portal with repository from serverless application registry. All you've to provide is the S3 bucket names for storing the API catalog, Dev Portal Static site and Cognito Domain Name/Prefix to sign in page URL's
If you want to look at the designer view of the cloud formation template...
Well, don't get bogged down by the bells and whistles in the resource stack above, but it has got everything that's needed for the user management through Cognito Identity pool, DynamoDB tables for users, feedback, SNS notifications and 12 lambda functions for managing s3 bucket updates, cognito, cloud front security headers and API gateway where we will be able to manage the throttling, deploying more API's in various stages, API keys and client certificates.
When you see this Developer Portal, it means you've reached the end of the journey of what is takes from designing API to putting it up in the Developer Portal. You will be able to now put your API catalog in the s3 buckets and manage the users via Cognito and manage how your API's are accessed.