Build API clients for Ruby

In this tutorial, you build a sample app in Ruby that calls a REST API that doesn't require authentication.

Required tools

Create a project

Create a directory to contain the new project, and create a new file named Gemfile in it.

Add dependencies

Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the abstraction package. Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.

HTTP (Kiota default Faraday-based implementation)
JSON serialization (Kiota default)
Text serialization (Kiota default)
Form serialization (Kiota default)
Multipart serialization (Kiota default)

For this tutorial, use the default implementations.

Edit your Gemfile and add the following code.

source 'https://rubygems.org'

ruby ">= 3.3.0"

gem "microsoft_kiota_abstractions"
gem "microsoft_kiota_faraday"
gem "microsoft_kiota_serialization_json"
gem "microsoft_kiota_serialization_text"
gem "microsoft_kiota_serialization_form"
gem "microsoft_kiota_serialization_multipart"

To install dependencies, run the following command.
```
bundle install
```

Generate the API client

Kiota generates API clients from OpenAPI documents. Create a file named posts-api.yml and add the following.

openapi: '3.0.2'
info:
  title: JSONPlaceholder
  version: '1.0'
servers:
  - url: https://jsonplaceholder.typicode.com/

components:
  schemas:
    post:
      type: object
      properties:
        userId:
          type: integer
        id:
          type: integer
        title:
          type: string
        body:
          type: string
  parameters:
    post-id:
      name: post-id
      in: path
      description: 'key: id of post'
      required: true
      style: simple
      schema:
        type: integer

paths:
  /posts:
    get:
      description: Get posts
      parameters:
      - name: userId
        in: query
        description: Filter results by user ID
        required: false
        style: form
        schema:
          type: integer
          maxItems: 1
      - name: title
        in: query
        description: Filter results by title
        required: false
        style: form
        schema:
          type: string
          maxItems: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/post'
    post:
      description: 'Create post'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
  /posts/{post-id}:
    get:
      description: 'Get post by ID'
      parameters:
      - $ref: '#/components/parameters/post-id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
    patch:
      description: 'Update post'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post'
      parameters:
      - $ref: '#/components/parameters/post-id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'
    delete:
      description: 'Delete post'
      parameters:
      - $ref: '#/components/parameters/post-id'
      responses:
        '200':
          description: OK

This file is a minimal OpenAPI description that describes how to call the /posts endpoint in the JSONPlaceholder REST API.

You can then use the Kiota command line tool to generate the API client classes.

kiota generate -l ruby -c PostsClient -n KiotaPosts -d posts-api.yml -o ./client

Tip

Add --exclude-backward-compatible if you want to reduce the size of the generated client and are not concerned about potentially source breaking changes with future versions of Kiota when updating the client.

Create the client application

Create a file in the root of the project named main.rb and add the following code.

# frozen_string_literal: true
require 'microsoft_kiota_abstractions'
require 'microsoft_kiota_faraday'
require 'microsoft_kiota_serialization_json'
require_relative './client/posts_client'

# API requires no authentication, so use the anonymous
# authentication provider
auth_provider = MicrosoftKiotaAbstractions::AnonymousAuthenticationProvider.new
# Create request adapter using the Faraday-based implementation
request_adapter = MicrosoftKiotaFaraday::FaradayRequestAdapter
  .new(auth_provider,
       MicrosoftKiotaSerializationJson::JsonParseNodeFactory.new,
       MicrosoftKiotaSerializationJson::JsonSerializationWriterFactory.new)
# Create the API client
client = KiotaPosts::PostsClient.new(request_adapter)

# GET /posts
all_posts = client.posts.get.resume
puts "Retrieved #{all_posts.length} posts."

# GET /posts/{id}
specific_post_id = 5
specific_post = client.posts.by_post_id(specific_post_id).get.resume
puts "Retrieved post - ID: #{specific_post.id}, " \
     "Title: #{specific_post.title}, " \
     "Body: #{specific_post.body}"

# POST /posts
new_post = KiotaPosts::Models::Post.new
new_post.user_id = 42
new_post.title = 'Testing Kiota-generated API client'
new_post.body = 'Hello world!'

created_post = client.posts.post(new_post).resume
puts "Created new post with ID: #{created_post.id}"

# PATCH /posts/{id}
update = KiotaPosts::Models::Post.new
# Only update title
update.title = 'Updated title'

updated_post = client.posts.by_post_id(specific_post_id).patch(update).resume
puts "Updated post - ID: #{updated_post.id}, " \
     "Title: #{updated_post.title}, " \
     "Body: #{updated_post.body}"

# DELETE /posts/{id}
client.posts.by_post_id(specific_post_id).delete.resume

Note

The JSONPlaceholder REST API doesn't require any authentication, so this sample uses the AnonymousAuthenticationProvider. For APIs that require authentication, use an applicable authentication provider.

Run the application

To start the application, run the following command in your project directory.

bundle exec ruby main.rb