APIs

[Overview] (#overview)
- [Encapsulation] (#encapsulation-through-3rd-parties)
  - [local libraries/gems] (#api-local-gemlibray-figure)
  - [remote web services/resources] (#remote-apis)
- [serialization] (#serialization)
  - xml
  - json
APIs Using Ruby
- Ruby & Ruby gems
- Ruby solution from scratch
Exercise with Braintree

Overview

###Encapsulation through 3rd parties API : An application programming interface (API) specifies how some software components should interact with each other.

Software components : An individual software component is a software package, a web service, a web resource, or a module that encapsulates a set of related functions (or data).

Better definition of API?

API specifies how:

a software package
a web service
a web resource
or a module encapsulates a set of related functions ( or data )

functions -> messages or methods used within the context of peer to peer communication

So the consise definition becomes:

API documents the interaction or delivery of messages between any of the following:

a software package
a web service
a web resource
or a module

API local gem/library figure

###remote APIs

When used in the context of web development, an API is typically defined as a set of Hypertext Transfer Protocol (HTTP) request messages, along with a definition of the structure of response messages, which is usually in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format.

API figure

The practice of publishing APIs has allowed web communities to create an open architecture for sharing content and data between communities and applications. In this way, content that is created in one place can be dynamically posted and updated in multiple locations on the web:

Photos can be shared from sites like Flickr and Photobucket to social network sites like Facebook and MySpace.
Content can be embedded, e.g. embedding a presentation from SlideShare on a LinkedIn profile.
Content can be dynamically posted. Sharing live comments made on Twitter with a Facebook account, for example, is enabled by their APIs.
Video content can be embedded on sites served by another host.
User information can be shared from web communities to outside applications, delivering new functionality to the web community that shares its user data via an open API. One of the best examples of this is the Facebook Application platform. Another is the Open Social platform.

###Serialization

The process in which we take an existing data structure and transfer it through the network.

<td>
  <pre>
    <code>
    {
        a: 1,
        b: 2,
        c: 3
    }
    </code>
  </pre>
</td>

<td>
  <pre><code>
  &lt;a&gt; 1 &lt;/a&gt;
  &lt;b&gt; 2 &lt;/b&gt;
  &lt;c&gt; 3 &lt;/c&gt;
  </code></pre>
</td>

<td>
  <pre><code>
  {
    "a": 1,
    "b": 2,
    "c": 3
  }
  </code></pre>
</td>

Ruby	Ruby 1.9+	XML	JSON
`{ :a => 1, :b => 2, :c => 3 }`

APIs Using Ruby

libraries
- software libraries included with ruby auto magically
gems
- Ruby libraries written/tested/published by the community which ranges from developers
- encourages software reuse few bugs avoid rebuilding the wheel.
3rd party APIs + existing gem
- The third-party software component market thrives because many programmers believe that component oriented development improves the efficiency and the quality of developing custom applications

As software engineers that aspire to build signature applications. We will test various ingredients (building blocks aka gems) in order to produce the best dish we can.

If it comes down to it we may need to make our own ingredients from scratch ... yet If we want to compete in todays market we can speed up this process by knowing and understanding the world of gems and how this gives us a foundation of solid building blocks when producing MVP's.

analogy of gems in a cajun restaurant

In a kitchen a gem would essentially be prep work before the chef begins to cook.

If the client requests gumbo, one essential time consuming ingredient would be the Roux.

(cooking and time ... slower the better )

If the cook were to always prepare the roux for each dish this could add complexity and time when preparing a single dish.

Instead restaurants have workers prepare these essential building blocks so that the line cooks/chefs can quickly prepare dishes for their consumers.

Summary of gems/libraries

Similarly companies or 3rd parties will provide us ruby developers with building blocks to enable us to integrate our applications to their software.

As a decision maker in manufactoring software, your discretion and or own cross examination, A/B testing, or researching various ingredients (or gems) ultimately help to improve your final delivery.

where do we stand with gems?

As you travel through the ruby world your role may be anywhere from:

gem user
gem contributor
gem author
gem design pattern interpretor (all of the above)

####Segway to todays exercise

Problem : we need to connect our ruby application to a remote 3rd party service

Basic ruby design decision flow

Our role as software engineers is to provide solutions existing or non existing and work with companies.

Here's where we as ruby developers spend most of our time is understanding existing solutions so we can combine extend or rebuild them in our day to day efforts.

Implementing home cooked solutions is the best way to learn ruby or compare it against and existing gem to discover different: patterns, solutions or optimizations.

Exercise with Braintree

what we are going to do visually

For our exercise we are going to focus on credit card processing using a ruby script. This exemplify's the use of an API as if we were to house private sensitive data on our own local machines would require security licensing plus fees & routine inspections.

Point is we can piggy back off of braintrees existing infrastucture using code examples provided by braintree which not only provides solutions in ruby but many other existing languages/platforms

Additionally I wanted this to be a brief introduction to gems to expose how we can perform powerful secure functionality without having to worry about:

authentication
ssl encryption
parsing XML/JSON

API figure

You are a Store owner who wishes to begin selling merchandise through your website. You already have a nicely designed page. All we need to do now is submit transactions to a 'Payment Gateway' using ruby to add this feature to our existing Ruby application. To begin please [clone this] (https://github.com/copremesis/api_braintree.git) repo.

We'll attempt to run this as is and if we run into any pitfalls will work together as a team to determine what missing pieces of the puzzle are missing.

I've put together dashboard to provide peers visual/audio feedback whenever a transaction is performed Credentials are already provided in the braintree.rb. After you are able to perform a sale transaction ... the next exercise is to perform a VOID. To assist I've done some Google-ing where you can track down

code documetation to perform this action.

Braintree Ruby Documentation

####Ruby Solution from Scratch

Keep in mind we are here to learn how to build solutions using existing solutions hence Gems. However, companies change technology and may even fall out of cyberspace. Our role as software engineers is to continue building bridges to help assit other developers along their journey.

I hope that I scratched the surface enough to open the door to a world of APIs and leave you inspired to build rich applications with many fine ingredients.

Happy Hacking!!!

--Rob

Most Basic Sale Code Snippet

result = Braintree::Transaction.sale(
  :amount => "7.77",
  :credit_card => {
    :number => "4111111111111111",
    :expiration_date => "05/14"
  }
)

More robust example

result = Braintree::Transaction.sale(
  :amount => "8.01",
  :order_id => "order id",
  :credit_card => {
    :number => "5105105105105100",
    :expiration_date => "05/2012",
    :cvv => "111"
  },
  :customer => {
    :first_name => "__FIRST_NAME__",
    :last_name => "__LAST_NAME__",
    :company => "MakerSquare",
    :website => "http://www.themakersquare.com",
    :email => "__YOUR_EMAIL__"
  }
)

#Whoami Rob Ortiz

https://github.com/copremesis twitter: @copremsis email: rob@dragonwrench.com [slides] (https://github.com/copremesis/api_braintree/blob/master/api.md)

Companies I've worked with:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

APIs

Overview

API local gem/library figure

API figure

APIs Using Ruby

analogy of gems in a cajun restaurant

Summary of gems/libraries

where do we stand with gems?

Basic ruby design decision flow

Exercise with Braintree

what we are going to do visually

API figure

Most Basic Sale Code Snippet

More robust example

Files

api.md

Latest commit

History

api.md

File metadata and controls

APIs

Overview

API local gem/library figure

API figure

APIs Using Ruby

analogy of gems in a cajun restaurant

Summary of gems/libraries

where do we stand with gems?

Basic ruby design decision flow

Exercise with Braintree

what we are going to do visually

API figure

Most Basic Sale Code Snippet

More robust example