m REST API design and tools

Owned by jim mason
Last updated: Jul 12, 2023 by jimm1
15 min read



Key Points

  1. OpenAPI is the open api standard built from Swagger open-source
  2. SwaggerHub is an online api design center
  3. personal account is free but very limited
  4. Swagger Team is $15 per month per user  ( expensive $180 per year per user )


References

Reference_description_with_linked_URLs_______________________Notes______________________________________________________________


m RESTREST design concepts


OpenAPI vs. Swagger: 5 Reasons You Should Use Both - 2022 article

OpenAPI vs. Swagger: 5 Reasons You Should Use Both - 2022 article

What's the Difference Between OpenAPI and Swagger?
Why Use OpenAPI or Swagger?

Swagger is now Openapi search


https://swagger.io/docs/Swagger OpenAPI docs home
https://swagger.io/docs/specification/about/What is OpenAPI?
https://swagger.io/docs/specification/about/Why learn OpenAPI?
https://swagger.io/resources/articles/documenting-apis-with-swagger/How to doc api with OpenAPI docs
https://swagger.io/blog/api-design/openapi-3-0-specification-training/How to doc api with OpenAPI Webinar
https://medium.com/better-programming/restful-api-design-step-by-step-guide-2f2c9f9fcdbfRESTful API design guide - medium

SwaggerHub home online

SwaggerHub pricing options / features


Designing_APIs_with_Swagger_and_OpenAPI_v9.pdf link

Designing_APIs_with_Swagger_and_OpenAPI_v9.pdf file

has api server codegen for nodejs only
https://swagger.io/docs/open-source-tools/swagger-codegen/generates skeleton for api server and client sdk
https://github.com/swagger-api/swagger-codegen

Designing_APIs_A Beginners Guide to Code Generation for REST APIs sample link

Designing_APIs_A Beginners Guide to Code Generation for REST APIs (free sample).pdf file








https://microservices.io/Microservices pattern and frameworks site







Key Concepts



REST API Design Concepts

https://medium.com/better-programming/restful-api-design-step-by-step-guide-2f2c9f9fcdbf

As software developers, most of us use or build REST APIs in day to day life. APIs are the default means of communication between the systems. Amazon is the best example of how APIs can be efficiently used for communication.

In this article, I am going to talk about how to design your RESTful APIs better to avoid common mistakes.

Some of you might have been already aware of Jeff Bezos’ mandate to the developers in Amazon. If you never got a chance to hear about it, the following points are the crux of it.

  1. All teams will henceforth expose their data and functionality through service interfaces.
  2. Teams must communicate with each other through these interfaces.
  3. There will be no other form of interprocess communication allowed — no direct linking, no direct reads of another team’s data store, no shared-memory model, no back doors whatsoever. The only communication allowed is via service interface calls over the network.
  4. It doesn’t matter what technology they use. HTTP, Corba, Pubsub, custom protocols — doesn’t matter. Bezos doesn’t care.
  5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
  6. Anyone who doesn’t do this will be fired.

Eventually, this turned out to be the key to Amazon’s success. Amazon could build scalable systems and later could also offer those as services like Amazon Web Services.

Now let’s understand the principles we should follow while designing the RESTful APIs.

Keep it simple

We need to make sure that the base URL of the API is simple. For example, if we want to design APIs for products, it should be designed like:

/products
/products/12345

The first API is to get all products and the second one is to get a specific product.

Use nouns and not the verbs

A lot of developers make this mistake. They generally forget that we have HTTP methods with us to describe the APIs better and end up using verbs in the API URLs. For instance, API to get all products should be:

/products

and not as shown below

/getAllProducts

Some common URL patterns, I have seen so far.

Use of the right HTTP methods

RESTful APIs have various methods to indicate the type of operation we are going to perform with this API.

  • GET — To get a resource or collection of resources.
  • POST — To create a resource or collection of resources.
  • PUT/PATCH — To update the existing resource or collection of resources.
  • DELETE — To delete the existing resource or the collection of resources.

We need to make sure we use the right HTTP method for a given operation.

Use plurals

This topic is a bit debatable. Some people like to keep the resource URL with plural names while others like to keep it singular. For instance —

/products/product

I like to keep it plural since it avoids confusion about whether we are talking about getting a single resource or a collection. It also avoids adding additional things like attaching all to the base URL e.g. /product/all

Some people might not like this but my only suggestion is to keep it uniform across the project.

Use parameters

Sometimes we need to have an API which should be telling more story than just by id. Here we should make use of query parameters to design the API.

  • /products?name=’ABC’ should be preferred over /getProductsByName
  • /products?type=’xyz’ should be preferred over /getProductsByType

This way you can avoid long URLs with simplicity in design.

Use proper HTTP codes

We have plenty of HTTP codes. Most of us only end up using two — 200 and 500! This is certainly not good practice. Following are some commonly used HTTP codes.

  • 200 OK — This is most commonly used HTTP code to show that the operation performed is successful.
  • 201 CREATED — This can be used when you use the POST method to create a new resource.
  • 202 ACCEPTED — This can be used to acknowledge the request sent to the server.
  • 400 BAD REQUEST — This can be used when client-side input validation fails.
  • 401 UNAUTHORIZED / 403 FORBIDDEN— This can be used if the user or the system is not authorized to perform a certain operation.
  • 404 NOT FOUND— This can be used if you are looking for a certain resource and it is not available in the system.
  • 500 INTERNAL SERVER ERROR — This should never be thrown explicitly but might occur if the system fails.
  • 502 BAD GATEWAY — This can be used if the server received an invalid response from the upstream server.

Versioning

Versioning of APIs is very important. Many different companies use versions in different ways. Some use versions as dates while some use versions as query parameters. I generally like to keep it prefixed to the resource. For instance:

/v1/products
/v2/products

I would also like to avoid using /v1.2/products, as it implies the API would be frequently changing. Also, dots (.) might not be easily visible in the URLs. So keep it simple.

It is always good practice to keep backward compatibility so that if you change the API version, consumers get enough time to move to the next version.

Use pagination

Use of pagination is a must when you expose an API which might return huge data, and if proper load balancing is not done, the consumer might end up bringing down the service. We need to always keep in mind that the API design should be full proof and fool proof.

Use of limit and offset is recommended here. For example, /products?limit=25&offset=50. It is also advised to keep a default limit and default offset.

Supported formats

It is also important to choose how your API responds. Most of the modern day applications should return JSON responses, unless you have a legacy app which still needs to get an XML response.

Use proper error messages

It is always good practice to keep a set of error messages the application sends and respond to that with proper id. For example, if you use Facebook graph APIs, in case of errors, it returns a message like this:

{
  "error": {
    "message": "(#803) Some of the aliases you requested do not exist: products",
    "type": "OAuthException",
    "code": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

I have also seen some examples in which people return a URL with an error message, which tells you more about the error message and how to handle it as well.

Use of OpenAPI specifications

In order to keep all teams in your company abide by certain principles, use of OpenAPI specification can be useful. OpenAPI allows you to design your APIs first and share that with the consumers in an easier manner.

Conclusion

It is quite evident that if you want to communicate better, APIs are the way to go. But if they are designed badly then it might increase confusion. So put your best effort in designing well, and the rest is just the implementation.


Other API Best Practice Tips

https://www.linkedin.com/posts/rajkgrover_apis-restful-data-activity-7075505032544030720-NYNa?utm_source=share&utm_medium=member_desktop

Digital Transformation Tip 015: 15 Best Practices for #APIs

1.    Design for clear purpose, simplicity, and user centered approach
2.    Follow #RESTful principles
3.    Provide comprehensive documentation
4.    Version your APIs
5.    Use clear and consistent naming conventions
6.    Use proper authentication and authorization mechanism
7.    Handle errors effectively
8.    Ensure #data validation and consistency
9.    Implement rate limiting and throttling
10. Incorporate #security standards
11. Optimize for performance
12. Monitor, log and analyse API usage
13. Plan for scalability, extensibility and version deprecation
14. Support developer community
15. Test, evolve and iterate


API Technical Capabilties


Strategic Components of APIs


OpenAPI

https://swagger.io/docs/specification/about/


What Is OpenAPI?

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

  • Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
  • Operation parameters Input and output for each operation
  • Authentication methods
  • Contact information, license, terms of use and other information.

API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification

What Is Swagger?

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include:

  • Swagger Editor – browser-based editor where you can write OpenAPI specs.
  • Swagger UI – renders OpenAPI specs as interactive API documentation.
  • Swagger Codegen – generates server stubs and client libraries from an OpenAPI spec.

Why Use OpenAPI?

The ability of APIs to describe their own structure is the root of all awesomeness in OpenAPI. Once written, an OpenAPI specification and Swagger tools can drive your API development further in various ways:

  • Design-first users: use Swagger Codegen to generate a server stub for your API. The only thing left is to implement the server logic – and your API is ready to go live!
  • Use Swagger Codegen to generate client libraries for your API in over 40 languages.
  • Use Swagger UI to generate interactive API documentation that lets your users try out the API calls directly in the browser.
  • Use the spec to connect API-related tools to your API. For example, import the spec to SoapUI to create automated tests for your API.
  • And more! Check out the open-source and commercial tools that integrate with Swagger.


OpenAPI Tools


from .. A Beginners Guide to 

  1. There is no doubt that Swagger Codegen is not the only code generator available on the
    market so why choose Swagger Codegen? Here are a couple of points to convince you
    Swagger Codegen is the obvious choice:
    Swagger Codegen is completely free and open-source with Apache License version
    2.0. The auto-generated files are not licensed so you can apply whatever software
    license to the auto-generated code as you deem appropriate.
  2. Swagger Codegen, with 5000+ stars on the Github project page10 and 9000+
    commits, has a vibrant and growing community. More than 700 software developers
    all over the world have filed a Pull Request, which is the standard way to propose
    code changes in git, to make Swagger Codegen better. You will find many activities
    related to Swagger Codegen in StackOverflow, Twitter, Github and other social
    networks. For a list of presentations, videos, tutorials and eBooks on Swagger
    Codegen, please refer to the README in the Github repository11.
  3. Swagger Codegen supports more than 30 API clients, 20 server stubs and API
    documentation. Recently, we just added support for Kotlin client generator12 and
    more generators such as PowerShell13, Lua14, Rust15 and Ada16 are being worked on
    by the awesome community.



Swagger Editor - Open Source

https://swagger.io/docs/open-source-tools/swagger-editor/


The Swagger Editor is an open source editor to design, define and document RESTful APIs in the Swagger Specification. The source code for the Swagger Editor can be found in GitHub.

GitHub: https://github.com/swagger-api/swagger-editor

Download

Using the Editor on the Web

The Editor works in any web browser, and can be hosted locally or accessed from the web.

Take Me To The Web Version

Using the Editor on a local machine

You can run and use the Swagger Editor on your machine as well.

Prerequisites

The following dependencies would need to be installed on your machine before downloading and running the Swagger Editor.

Once NodeJS is installed successfully, please install all the npm dependencies using

npm install;

Setup with http-server module from GitHub

The Swagger Editor can be found in this public repository on GitHub.

Please run the following to run the Editor using the http-server module from GitHub. After downloading the latest version from Github, you will need to run these scripts on your terminal.

  1. npm install -g http-server
  2. wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
  3. unzip swagger-editor.zip
  4. http-server swagger-editor
Setup from Docker

The Swagger Editor can be found in this public repository on Docker.

Please run the following to run the Editor in your local machine from Docker.

  1. docker pull swaggerapi/swagger-editor
  2. docker run -p 80:8080 swaggerapi/swagger-editor

Contribute

The Swagger Editor is an open source project under the Apache license. You can contribute to the project with suggestions, ideas, bug reports and pull requests in the Swagger Editor GitHub repository.

Please run the following to to see the Editor’s source code and work on the project from your local machine.

  1. git clone https://github.com/swagger-api/swagger-editor.git
  2. cd swagger-editor
  3. npm install
  4. npm run build
  5. npm start

Common issues:

  • If npm start does not work, delete the node_modules folder, then run npm install and npm start
  • If there is a problem with dist folder after cloning, go to the root and run npm run build


Swagger UI - Open Source

https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

Distribution channels

NPM Registry

We publish two modules to npm: swagger-ui and swagger-ui-dist.

swagger-ui is meant for consumption by JavaScript web projects that include module bundlers, such as Webpack, Browserify, and Rollup. Its main file exports Swagger UI's main function, and the module also includes a namespaced stylesheet at swagger-ui/dist/swagger-ui.css. Here's an example:

  1. import SwaggerUI from 'swagger-ui'
  2. // or use require, if you prefer
  3. const SwaggerUI = require('swagger-ui')
  4. SwaggerUI({
  5. dom_id: '#myDomId'
  6. })

In contrast, swagger-ui-dist is meant for server-side projects that need assets to serve to clients. The module, when imported, includes an absolutePath helper function that returns the absolute filesystem path to where the swagger-ui-dist module is installed.

Note: we suggest using swagger-ui when your tooling makes it possible, as swagger-ui-dist will result in more code going across the wire.

The module's contents mirrors the dist folder you see in the Git repository. The most useful file is swagger-ui-bundle.js, which is a build of Swagger UI that includes all the code it needs to run in one file. The folder also has an index.html asset, to make it easy to serve Swagger UI like so:

  1. const express = require('express')
  2. const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
  3. const app = express()
  4. app.use(express.static(pathToSwaggerUi))
  5. app.listen(3000)

The module also exports SwaggerUIBundle and SwaggerUIStandalonePreset, so if you're in a JavaScript project that can't handle a traditional npm module, you could do something like this:

  1. var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle
  2. const ui = SwaggerUIBundle({
  3. url: "https://petstore.swagger.io/v2/swagger.json",
  4. dom_id: '#swagger-ui',
  5. presets: [
  6. SwaggerUIBundle.presets.apis,
  7. SwaggerUIBundle.SwaggerUIStandalonePreset
  8. ],
  9. layout: "StandaloneLayout"
  10. })

SwaggerUIBundle is equivalent to SwaggerUI.

Docker

You can pull a pre-built docker image of the swagger-ui directly from Docker Hub:

  1. docker pull swaggerapi/swagger-ui
  2. docker run -p 80:8080 swaggerapi/swagger-ui

Will start nginx with Swagger UI on port 80.

Or you can provide your own swagger.json on your host

  1. docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

The base URL of the web application can be changed by specifying the BASE_URL environment variable:

  1. docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

This will serve Swagger UI at /swagger instead of /.

For more information on controlling Swagger UI through the Docker image, see the Docker section of the Configuration documentation.

unpkg

You can embed Swagger UI's code directly in your HTML by using unpkg's interface:

  1. <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
  2. <!-- `SwaggerUIBundle` is now available on the page -->

See unpkg's main page for more information on how to use unpkg.


Swagger Codegen - Open Source

https://swagger.io/docs/open-source-tools/swagger-codegen/

The Swagger Codegen is an open source code-generator to build server stubs and client SDKs directly from a Swagger defined RESTful API. The source code for the Swagger Codegen can be found in GitHub.

GitHub: https://github.com/swagger-api/swagger-codegen

Compatibility

Swagger Codegen VersionRelease DateSwagger Spec CompatibilityNotes
2.3.0 (upcoming minor release)TBD1.0, 1.1, 1.2, 2.0Minor releases with breaking changes
2.2.2 (upcoming patch release)TBD1.0, 1.1, 1.2, 2.0Patch release (without breaking changes)
2.2.1 (current stable)2016-08-071.0, 1.1, 1.2, 2.0tag v2.2.1
2.1.62016-04-061.0, 1.1, 1.2, 2.0tag v2.1.6
2.0.172014-08-221.1, 1.2tag v2.0.17
1.0.42012-04-121.0, 1.1tag v1.0.4

Installation

Prerequisites

The following dependencies would need to be installed on your machine before downloading and running the Swagger Codegen.

  • Java, version 7 or higher

Installation with Homebrew

If you have a Mac or a Linux environment, then you could use Homebrew to install the Swagger Codegen.

brew install swagger-codegen

Installation from Maven Central

All versions of the Swagger Codegen project can be found on Maven Central. Visit this folder on Maven, and choose the appropriate version (we recommend the latest version).

You could download and run the executable .jar file (for example, swagger-codegen-cli-2.2.1.jar)

Alternatively, you could use the wget command as well.

wget {link address of the executable .jar file}

Example:

  1. wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar

Usage

For the sake of simplicity, we will assume you have the swagger-codegen-cli-2.2.1 installed. Please visit the installation section of the Swagger Codegen to learn about how to get the Codegen on your machine.

List of supported languages

To get a list of languages supported by the Swagger Codegen -

If you have Homebrew installed:

swagger-codegen

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar

Help options in terminal

To see the various help section options of the Swagger Codegen -

If you have Homebrew installed:

swagger-codegen help

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar help

Once you have the various help section options, you can learn about a specific topic.

If you have Homebrew installed:

swagger-codegen help <command>

Example:

swagger-codegen help generate

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar help <command>

Example:

java -jar swagger-codegen-cli-2.2.1.jar help generate

To see the various config help section options for specific languages supported by the Swagger Codegen -

If you have Homebrew installed:

swagger-codegen config-help -l <language name>

Example:

swagger-codegen config-help -l php

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar config-help -l <language name>

Example:

java -jar swagger-codegen-cli-2.2.1.jar config-help -l php

Generating Code

To generate code from an existing swagger specification -

If you have Homebrew installed:

swagger-codegen generate -i <path of your Swagger specification> -l <language>

Example:

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l csharp

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar generate -i <path of your Swagger specification> -l <language> ` Example:

java -jar swagger-codegen-cli-2.2.1.jar generate -i http://petstore.swagger.io/v2/swagger.json -l csharp

In the above code, we pass two arguments : - i and -l. -i is used to specify the path of your API’s specification. -l is used to specify the language you want to generate the code for your specified API’s specification

The Codegen creates a README file with all the information for running and building the API. Each language creates a different README, so please go through it to learn about how to build your Swagger defined API.

Contribute

The Swagger Codegen is an open source project under the Apache license. You can contribute to the project with suggestions, ideas, bug reports and pull requests in the GitHub repository, found here -https://github.com/swagger-api/swagger-codegen.

Guidelines
Before submitting an issue
  • If you're not using the latest master to generate API clients or server stubs, please give it another try by pulling the latest master as the issue may have already been addressed. Ref: Getting Started
  • Search the open issue and closed issue to ensure no one else has reported something similar before.
  • File an issue ticket by providing all the required information.
  • Test with the latest master by building the JAR locally to see if the issue has already been addressed.
  • You can also make a suggestion or ask a question by opening an "issue".
Before submitting a PR
  • Search the open issue to ensure no one else has reported something similar and no one is actively working on similar proposed change.
  • If no one has suggested something similar, open an "issue" with your suggestion to gather feedback from the community.
  • It's recommended to create a new git branch for the change so that the merge commit message looks nicer in the commit history.
How to contribute
Code generators

All the code generators can be found in modules/swagger-codegen/src/main/java/io/swagger/codegen/languages

Templates

All the templates (mustache) can be found in modules/swagger-codegen/src/main/resources.

For a list of variables available in the template, please refer to this page

Style guide

Code change should conform to the programming style guide of the respective languages:

For other languages, feel free to suggest.

You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those.

For Vendor Extensions, please follow the naming convention below:

  • For general vendor extension, use lower case and hyphen. e.g. x-is-unique, x-content-type
  • For language-specified vendor extension, put it in the form of x-{lang}-{extension-name}. e.g. x-objc-operation-id, x-java-feign-retry-limit
  • For a list of existing vendor extensions in use, please refer to https://github.com/swagger-api/swagger-codegen/wiki/Vendor-Extensions. If you've addaed new vendor extensions as part of your PR, please update the wiki page.
Testing

To add test cases (optional) covering the change in the code generator, please refer to modules/swagger-codegen/src/test/java/io/swagger/codegen

To test the templates, please perform the following:

  • Update the Petstore sample by running the shell script under bin folder. For example, run ./bin/ruby-petstore.shto update the Ruby PetStore API client under samples/client/petstore/ruby For Windows, the batch files can be found under bin\windows folder. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI/Swagger spec from time to time. If you've questions or concerns, please open a ticket to start a discussion)
  • Run the tests in the sample folder, e.g. in samples/client/petstore/ruby, run mvn integration-test -rf :RubyPetstoreClientTests. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)
  • Finally, git commit the updated samples files: git commit -a (git add -A if added files with new test cases)

To start the CI tests, you can run mvn verify -Psamples (assuming you've all the required tools installed to run tests for different languages) or you can leverage http://travis-ci.org to run the CI tests by adding your own Swagger-Codegen repository.

Tips
  • Smaller changes are easier to review
  • [Optional] For bug fixes, provide a OpenAPI Spec to repeat the issue so that the reviewer can use it to confirm the fix
  • Add test case(s) to cover the change
  • Document the fix in the code to make the code more readable
  • Make sure test cases passed after the change (one way is to leverage https://travis-ci.org/ to run the CI tests)
  • File a PR with meaningful title, description and commit messages. A good example is PR-3306


Use Open API to Design REST API

https://swagger.io/blog/api-design/openapi-3-0-specification-training/

swagger.io-Documenting Your Existing APIs API Documentation Made Easy with OpenAPI Swagger.pdf

use SwaggerHub to generate Open API specs



SwaggerHub online Open API Design tool

https://app.swaggerhub.com/organizations/create-wizard?from-signup=true

jm9 Syn$

SwaggerHub url

Here is your personalized API URL

https://app.swaggerhub.com/apis/

s9561


API design concept

SCRUD all entitiy objects

define process objects with custom APIs


Open API Training for SwaggerHub

https://swagger.io/blog/api-design/openapi-3-0-specification-training/

OpenAPI 3.0, which is based on the original Swagger 2.0 specification, has emerged as the world’s standard for defining and describing RESTful APIs. The next version of the OpenAPI Specification – version 3.0 – is officially released, and comes with a host of rich, expressive capabilities for your API design and documentation. Some of these capabilities include support for describing callbacks, links to express relationships between operations, enhanced examples, and a simplified structure for better reusability. SwaggerHub now offers support for designing and documenting APIs with OpenAPI 3.0, as well as the ability to convert APIs defined with Swagger 2.0 to the latest version of the specification. In this free SwaggerHub training, we look at what’s new in OAS 3.0, and show a live demo of defining APIs using OAS 3.0 in SwaggerHub

video url



API Blueprint DSL

https://apiblueprint.org/




Potential Value Opportunities



Potential Challenges



Candidate Solutions



Step-by-step guide for Example



sample code block

sample code block



Recommended Next Steps