<commit_before># Smooth

Smooth provides a way of developing JSON APIs on top of SQL Databases that is, well, smooth. 

Smooth provides a ruby library and a front end graphical application
that make the process of developing APIs for your web and mobile
applications really productive. 

#### General idea: in the abstract

A resource is, generally, a database backed collection of models. A
resource can be accessed by users who have different roles and relations
to the data.  A resource is accessed in one of two ways: queries, and
commands.  The resource can be presented in different views.

#### The benefits of a declarative, data driven programming style

As a developer you get API interface inspection capabilities 
for free by coding your API in the smooth style.  These capabilities can give you a lot of power 
for your every day development practice.

Generating documentation, generating custom querying and reporting
tools, generating API client libraries, generating automated test code,
and a number of other tasks become much much easier.

#### The Smooth approach starts with declarations

In smooth we develop resources by describing or declaring data about the
different functions an API client will need access to to provide its
users the means of interacting with their data that they need.

##### Commands:

Commands handle API requests whose intent is to change data in the
resource. A user updating their profile. A person adding a new recipe
to their cookbook. A moderator removing a rude comment on their blog. 

We define the set of commands available and what information they
require:

- In what ways can a user change the data?
- What specific parameters must an API client pass to these commands?
- Describe what they mean for a developer?
- What type of data, what values?

##### Queries:

API clients often have large sets of data that they need to reduce to a  
manageable size to render in some view in their application or dynamic
page on their website.

- In what ways can a user or role filter the data? 
- Specifically what parameters would an API client pass? 
- What type of data, what values?
- Should a user only be allowed to see a hard coded subset of records? 

##### Serializers:

Given a query which returns a set of zero or more records, we will often
want to present this data in an optimized format.  We'll want to convert 
a specific timestamp into a description of the amount of time that has
passed.  We'll want to display individual things in a table, or maybe as a pie chart. 

In smooth we enumerate:

- In what ways would an API client want to see this data? 
- As individual objects? As a reduced / aggregated report?
- In what ways does the data change depending on who is looking at it?
- Are there different serializers for different roles?
- What are each of the attributes and what do they mean?

## Coding the smooth way 

There are a few distinctly different ways of working with code *sunglasses* smoothly.

- Use it in your rails application, edit the different classes of ruby
  objects whose file names, locations, and class names follow a familiar
  naming convention.

- Use it in a standalone ruby application as a rack compatible
  application or middleware.  File organization and class naming approach
  follows same familiar naming conventions.

- Use the DSL to build an entire application from one or more configuration
  files organized however you want.

- Use the smooth developer mode to build the structure of your API and
  resources visually and from a user interface.  Customize small methods
  with configuration, and if necessary, custom code.

- Use the smooth developer mode and don't write any code at all.<commit_msg>updating the readme with code samples<commit_after># Smooth

Smooth provides a way of developing JSON APIs on top of SQL Databases that is, well, smooth. 

Smooth provides a ruby library and a front end graphical application
that make the process of developing APIs for your web and mobile
applications really productive. 

#### General idea: in the abstract

A resource is, generally, a database backed collection of models. A
resource can be accessed by users who have different roles and relations
to the data.  A resource is accessed in one of two ways: queries, and
commands.  The resource can be presented in different views.

#### The benefits of a declarative, data driven programming style

As a developer you get API interface inspection capabilities 
for free by coding your API in the smooth style.  These capabilities can give you a lot of power 
for your every day development practice.

Generating documentation, generating custom querying and reporting
tools, generating API client libraries, generating automated test code,
and a number of other tasks become much much easier.

#### The Smooth approach starts with declarations

In smooth we develop resources by describing or declaring data about the
different functions an API client will need access to to provide its
users the means of interacting with their data that they need.

##### Commands:

Commands handle API requests whose intent is to change data in the
resource. A user updating their profile. A person adding a new recipe
to their cookbook. A moderator removing a rude comment on their blog. 

We define the set of commands available and what information they
require:

```ruby
resource "Books" do
  desc "Update a book's attributes"
  command :update do
    # Will ensure the command is run with
    # Book.accessible_to(current_user).find(id).
    scope :accessible_to

    params do
      duck :id, :method => :to_s

      optional do
        desc "the title of the book"
        string :title
      end
    end

    execute(:update)
  end
end
```

The DSL for commands allows us to document and code the
interface to define:

- In what ways can a user change the data?
- What specific parameters must an API client pass to these commands?
- Describe what they mean for a developer?
- What type of data, what values?

##### Queries:

API clients often have large sets of data that they need to reduce to a  
manageable size to render in some view in their application or dynamic
page on their website.

```ruby
  query do
    # calls `Book.accessible_to(current_user)`
    scope :accessible_to

    params do
      desc "The year the book was published (example: YYYY)"
      integer :year_published, operator: :gte

      desc "A partial string to filter the title by"
      string :title, operator: :like
    end

    role :admin do
      scope :all
    end
  end

```

The Query DSL lets us document and decide:

- In what ways can a user or role filter the data? 
- Specifically what parameters would an API client pass? 
- What type of data, what values?
- Should a user only be allowed to see a hard coded subset of records? 

##### Serializers:

Given a query which returns a set of zero or more records, we will often
want to present this data in an optimized format.  We'll want to convert 
a specific timestamp into a description of the amount of time that has
passed.  We'll want to display individual things in a table, or maybe as a pie chart. 

```ruby
  desc "The default serializer for book"
  serializer do
    desc "A unique id for the book", :type => :integer
    attribute :id

    desc "The title of the book", :type => :string
    attribute :title

    desc "The author of the book"
    has_one :author

    desc "Documentation for computed property"
    def computed_property
      object.created_at
    end

    desc "Another way for doing computed properties"
    computed(:another_computed_property) do
      object.created_at.to_i
    end
  end
```

In smooth's serializer DSL we document and decide:

- In what ways would an API client want to see this data? 
- As individual objects? As a reduced / aggregated report?
- In what ways does the data change depending on who is looking at it?
- Are there different serializers for different roles?
- What are each of the attributes and what do they mean?

## Coding the smooth way 

Using the Smooth API toolkit is possible:

- Use it in your rails application, edit the different classes of ruby
  objects whose file names, locations, and class names follow a familiar
  naming convention.

- Use it in a standalone ruby application as a rack compatible
  application or middleware.  File organization and class naming approach
  follows same familiar naming conventions.

- Use the DSL to build an entire application from one or more configuration
  files organized however you want.

- Use the smooth developer mode to build the structure of your API and
  resources visually and from a user interface.  Customize small methods
  with configuration, and if necessary, custom code.

- Use the smooth developer mode and don't write any code at all.
{'fraction_non_alphanumeric': 0.03943789664551224, 'fraction_numerical': 0.0, 'mean_word_length': 3.7599784250269686, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7159749', 'n_tokens_mistral': 2191, 'n_tokens_neox': 2087, 'n_words': 1369}