By the end of this blog, you will have understood below areas of API Lifecycle Management:

  1. Visualizing an API.
  2. Using API Designer
  3. Building API Specifications

Table of Contents

  1. Table of Contents
  2. The Importance of API Design
  3. Quick Introduction to Service Collection
  4. OpenAPI: Your Design Masterplan
    1. SAP API Designer: Visualize and Simplify
    2. Excercise: Creating our first API Specification
  5. Conclusion
  6. What is next?
    1. From Design to Reality
    2. The Design-First Mindset
  7. About Next Blog

In today’s interconnected world, APIs are the building blocks of modern applications. Well-designed APIs make developers’ lives easier and foster innovation. With SAP API Management, you have the tools to transform your API ideas into impactful digital services.

The Importance of API Design

While API Design does take time to master, at the crux of it it is about two things: “Entity” and “Operations to be done on this entitity” i.e. Create, Read, Update and Delete. There are a few more methods but these four together are called CRUD.

Imagine a simplified “Order Management API”:

Endpoint: /orders
Methods: 
    - GET    : Get list of orders
    - POST   : Creates a new order
    - PATCH  : Update an order
    - DELETE : Delete an order

This snippet reveals the underlying power of clarity in API design. It clearly communicates the entry point (/orders) to fetch, create, update and delete an order(s) with its different methods (GET, POST, PATCH, DELETE).

Quick Introduction to Service Collection

Our simple ‘Order API’ provides a starting point, but real-world applications typically manage dozens of interconnected entities. To handle this complexity, API endpoints may act as gateways to collections of services. Each service focuses on a specific entity, offering operations to create, read, update, or delete its data. Understanding and effectively implementing this service collection pattern is crucial for API providers building scalable and maintainable systems.

Note that entityId is optional but also depends on the API, sometimes you want to fetch (GET) or update (PATCH) information for particular entity, that you can do by providing entityId as parameter.

Also path prefix can be anything, which segregates two forms of an API, here their versioning separates them.

OpenAPI: Your Design Masterplan

The OpenAPI Specification (formerly Swagger) gives you a standard way to define APIs in a format readable by tools and humans alike. Think of it as a blueprint for your API, specifying routes, methods, expected data, and more.

We will go over a sample of Open API specification in our excercise section towards the end of this blog.

SAP API Designer: Visualize and Simplify

SAP API Management features an intuitive API Designer. Below are the steps which we will do in our excercise to create our first API specification as per Open API standard.

  1. Structure It: Visually model your API’s endpoints and available methods (like those for our Order Management API).
  2. Add Detail: Describe input parameters and the expected formats of API responses.
  3. Secure It: Define authentication methods (using standards like OAuth 2.0) to control access.

In your API management console you can navigate to API designer as below:

Excercise: Creating our first API Specification

Objective

We want to build API specification for a simple “Greeting and Feedback” API. It has two operations:

  1. It receives a name from client in the URL and it needs to return a greeting e.g. “Hello John”.
  2. It receives a feedback text from Client and it needs to submit it and return acknowledgement upon successful submission.

By the end of our excercise, broadly this is how it should look:

When you first see API designer, it is comprised of two parts:

  1. UI Doc View - UI showing API specification visually
  2. Code Editor - Which we will edit to create specification

This is default view. We will edit code editor and along with that we will understand what each block does. At this stage, deep diving into everything will create information overload, so we will try to get close to our “to be” API specification as close as we can.

So first we will edit our code editor with below code:

openapi: 3.0.3 
info:
  title: 
  description: 
  version: 1.0.0
servers:
  - url: https://api.mydomain.com/v1
paths:
components:

Notice how “UI Doc View” is nearly empty owing to our specifications being nearly nil at this point. We will touch upon each block as we progress.

"info" block - we document title and purpose of the the API for which we are building specification. Lets populate it.

info:
  title: Greeting and Feedback API  
  description: Demo API
  version: 1.0.0

"servers" block: This the host URL where your service is expected to be deployed. You can provide multiple URLs for different environments. At this point we will leave it as shown originally.

In case you are interested how to specify multiple URLs:

servers: 
  - url: https://api.example.com/v1
    description: Production server
  - url: https://sandbox.example.com/v1 
    description: Sandbox server
  - url: https://{subdomain}.example.com/{version}
    description: Custom server 
    variables: 
      subdomain:
        default: api
      version: 
        enum: 
          - v1
          - v2 
        default: v1

“paths” block: paths are the pointers to resouces hosted by the server which you are trying to invoke. Below is the breakdown of its smaller specification:

We try to cover as much as information required to make call for each path. Lets populate it.

paths:
  '/greetings/{name}': 
    get: 
      summary: get custom greetings
      description: Provide the name for which you need greeting
      parameters: 
        - name: name
          in: path
          description: name of the user
          required: true
          schema:
            type: string
      responses:
        '400':
          description: No user found
      security: 
        - customScheme: \[\]

  /submit-feedback:
    post:
      summary: Submit user feedback
      description: Accepts a feedback message for processing
      requestBody: # Defines the expected structure of the request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feedback'  # References reusable schema
      responses:
        '201':
          description: Feedback submitted
        '400':
          description: Invalid feedback data
        # ... other possible responses

You can ignore the red flags you see currently as they are referencing a part of specification which is yet to be created. Ideally, you will work on both blocks i.e. paths and components together.

“components” block: This block is like repository of blocks of information which other blocks use, it generally consists of two or more blocks. We will go over the basic two types:

  1. Schemas - This are skeletons of the message or data which will be used to populate complete request or response when a user invokes the API.
  2. SecuritySchemes - These the schemes we will opt for when securing any particular operation. e.g. the schemes will enforce the user to provide oauth token or API key or JWT token to be able to complete the API call successfully. You can have none, one or more security schemes.

Lets populate it, I have commented the part so that their purpose is clear:

components:
  # Schema block
  schemas:
    Feedback: #Feedback schema for the text to be passed in message body
      type: object
      properties: #consists of two field message and rating
        message: 
          type: string
          description: The user's feedback message
        rating:
          type: integer
          description: A numerical rating (optional)
          minimum: 1 #minimum value
          maximum: 5 #maximum value
  securitySchemes:
    basicAuth: #this is just the name of scheme
      type: http  #can have below value apikey, http, oauth, oauth2
      scheme: basic #additional fields will be enforced by editor based on type
    jwtAuth:
      type: http #for http JWT Authentication
      scheme: bearer # prefix the token with bearer
      bearerFormat: JWT  #type of token value
    customScheme: #customScheme which we will use for API specification
      type: apiKey
      in: header #will be passed in header
      name: string

You can ignore the warning for now, those are for the objects we have not used.

If you expand you operations now, this is how they appear:

Notice how the operations are nearly close to our objective, where we have two opearations for each of the purposes we set out to achieve as part of this excercise.

We are just designing at this point.

This is how you build specification. And of course, there is room for more exploration. Give it a try!

Conclusion

API Designer is instrumental in visualizing the contribution of an API to business value by providing a user-friendly interface to interact with the API documentation. It allows stakeholders, including business users, developers, and project managers, to easily understand the capabilities and functionalities offered by the API. Through API Designer’s interactive documentation, stakeholders can explore endpoints, parameters, and responses, facilitating better comprehension of how the API aligns with business requirements and objectives. Additionally, API Designer’s visual representation of API endpoints and data models aids in showcasing how the API can be leveraged to create value-added services or streamline existing business processes.

What is next?

From Design to Reality

Your OpenAPI specification unlocks exciting possibilities within SAP API Management:

  • API Proxies: Build API proxies that encapsulate your backend systems and enforce the policies defined in your design.
  • Publish and Promote: Get your API into the hands of developers by publishing it on your API portal.
  • Analyze and Improve: Analytics features pinpoint usage trends and highlight optimization opportunities.

The Design-First Mindset

SAP API Management puts exceptional API design within easy reach. Thinking creatively about your APIs and prioritizing clear communication paves the way for seamless interaction between systems and unlocks hidden business value.

About Next Blog

In the next blog, we will delve into developing an API, i.e., creating our first API proxy based on the OpenAPI specification we developed just now. Additionally, for the sake of understanding a wider range of topics, we will create another proxy with the help of an open-source API provider (NorthWind services), which we will use in all our future tutorials.

See you in next one.