GITHUB API design cheatsheet

API Design Cheat Sheet

  1. Build the API with consumers in mind–as a product in its own right.
    • Not for a specific UI.
    • Embrace flexibility / tunability of each endpoint (see #5, 6 & 7).
    • Eat your own dogfood, even if you have to mockup an example UI.
  2. Use the Collection Metaphor.
    • Two URLs (endpoints) per resource:
      • The resource collection (e.g. /orders)
      • Individual resource within the collection (e.g. /orders/{orderId}).
    • Use plural forms (‘orders’ instead of ‘order’).
    • Alternate resource names with IDs as URL nodes (e.g. /orders/{orderId}/items/{itemId})
    • Keep URLs as short as possible. Preferably, no more-than three nodes per URL.
  3. Use nouns as resource names (e.g. don’t use verbs in URLs).
  4. Make resource representations meaningful.
    • “No Naked IDs!” No plain IDs embedded in responses. Use links and reference objects.
    • Design resource representations. Don’t simply represent database tables.
    • Merge representations. Don’t expose relationship tables as two IDs.
  5. Support filtering, sorting, and pagination on collections.
  6. Support link expansion of relationships. Allow clients to expand the data contained in the response by including additional representations instead of, or in addition to, links.
  7. Support field projections on resources. Allow clients to reduce the number of fields that come back in the response.
  8. Use the HTTP method names to mean something:
    • POST – create and other non-idempotent operations.
    • PUT – update.
    • GET – read a resource or collection.
    • DELETE – remove a resource or collection.
  9. Use HTTP status codes to be meaningful.
    • 200 – Success.
    • 201 – Created. Returned on successful creation of a new resource. Include a ‘Location’ header with a link to the newly-created resource.
    • 400 – Bad request. Data issues such as invalid JSON, etc.
    • 404 – Not found. Resource not found on GET.
    • 409 – Conflict. Duplicate data or invalid data state would occur.
  10. Use ISO 8601 timepoint formats for dates in representations.
  11. Consider connectedness by utilizing a linking strategy. Some popular examples are:
  12. Use OAuth2 to secure your API.
    • Use a Bearer token for authentication.
    • Require HTTPS / TLS / SSL to access your APIs. OAuth2 Bearer tokens demand it. Unencrypted communication over HTTP allows for simple eavesdroppping and impersonation.
  13. Use Content-Type negotiation to describe incoming request payloads.For example, let’s say you’re doing ratings, including a thumbs-up/thumbs-down and five-star rating. You have one route to create a rating: POST /ratingsHow do you distinguish the incoming data to the service so it can determine which rating type it is: thumbs-up or five star?

    The temptation is to create one route for each rating type: POST /ratings/five_star and POST /ratings/thumbs_up

    However, by using Content-Type negotiation we can use our same POST /ratings route for both types. By setting the Content-Type header on the request to something like Content-Type: application/vnd.company.rating.thumbsup or Content-Type: application/vnd.company.rating.fivestar the server can determine how to process the incoming rating data.

  14. Evolution over versioning. However, if versioning, use the Accept header instead of versioning in the URL.
    • Versioning via the URL signifies a ‘platform’ version and the entire platform must be versioned at the same time to enable the linking strategy.
    • Versioning via the Accept header is versioning the resource.
    • Additions to a JSON response do not require versioning. However, additions to a JSON request body that are ‘required’ are troublesome–and may require versioning.
    • Hypermedia linking and versioning is troublesome no matter what–minimize it.
    • Note that a version in the URL, while discouraged, can be used as a ‘platform’ version. It should appear as the first node in the path and not version individual endpoints differently (e.g. api.example.com/v1/…).
  15. Consider Cache-ability. At a minimum, use the following response headers:
    • ETag – An arbitrary string for the version of a representation. Make sure to include the media type in the hash value, because that makes a different representation. (ex: ETag: “686897696a7c876b7e”)
    • Date – Date and time the response was returned (in RFC1123 format). (ex: Date: Sun, 06 Nov 1994 08:49:37 GMT)
    • Cache-Control – The maximum number of seconds (max age) a response can be cached. However, if caching is not supported for the response, then no-cache is the value. (ex: Cache-Control: 360 or Cache-Control: no-cache)
    • Expires – If max age is given, contains the timestamp (in RFC1123 format) for when the response expires, which is the value of Date (e.g. now) plus max age. If caching is not supported for the response, this header is not present. (ex: Expires: Sun, 06 Nov 1994 08:49:37 GMT)
    • Pragma – When Cache-Control is ‘no-cache’ this header is also set to ‘no-cache’. Otherwise, it is not present. (ex: Pragma: no-cache)
    • Last-Modified – The timestamp that the resource itself was modified last (in RFC1123 format). (ex: Last-Modified: Sun, 06 Nov 1994 08:49:37 GMT)
  16. Ensure that your GET, PUT, and DELETE operations are all idempotent. There should be no adverse side affects from operations.

github Platform Building cheat sheet

See also: [API Design Cheat Sheet](https://github.com/RestCheatSheet/api-cheat-sheet#api-design-cheat-sheet)

# Platform-Building Cheat Sheet

First off, we need to understand what is meant by the term **’platform’** for the organization.
In todays world, the term ‘platform’ is such an overused buzzword that it is largely meaningless.
Platforms exist at many levels in the technology stack: hardware, datacenter, database,
messaging, etc. and can also be used to describe ecosystems of user experiences.

The view presented here is decidedly business focused: the ‘platform’ is really the method
of exposing and growing the digital business model and its offerings. So, the following ground rules
define the platform as the digital server-side, back-end data and functionality, leaving the user
experiences to be crafted (whether mobile, web or other) on top of that business functionality.

This API-centric definition of ‘platform’ enables:

* Rapid user experience revision
* Consistent user experience across devices
* Better channel adaptation
* Faster and cheaper third-party integrations
* Increased innovation capabilities.

## Platform Ground Rules

1. **Mobile** applications are a first-class citizen and consumer of the platform.
* Making mobile a priority increases ease of use and adoption for everyone.
1. The platform exposes its data and functionality via a complete set of **RESTful APIs**.
* An API-based strategy maximizes reuse and flexibility.
1. All service interfaces and events are designed from the ground up to be **public facing**.
* Causes design for ease of use, flexibility and reuse.
1. Each team of developers access all APIs using their team’s own **registered developer key**.
* Improves security, auditability.
1. There is a **single token source** and format for all APIs.
* Assists in ease of use and ensures all functionality is available to consumers.
1. The platform will notify interested observers of all resource state changes via **fully-composed events**.
* Enables synchronization asynchronously (for all create, update, delete state changes).
1. All APIs use a **single identity** to represent the consumer / user.
* Enables analytics and reasoning about consumers.
1. All APIs have a **consistent look and feel**, and are documented at a single, publicly-available location.
* Maximizes reuse and ease of use.
1. No private interfaces. **No backdoors**. No shared databases across teams (Observe ‘Bounded Contexts’).
* Ensures the public interfaces are sound.
1. APIs are deployed in a **distributed, always-on** architecture (multi-node, multi-zone, and multi-region) with a discipline towards resilience.
* Horizontal scale on commodity hardware, global reach. Account for the inevitable failures.

Durbin Interchange Amendment Summary

The DURBIN amendment would bring regulation to the $20 billion per year debit interchange fee system.
The card issuing bank in a debit card transaction receives  interchange fees.
However, Visa and MasterCard set the debit interchange fee rates that apply to all banks within their networks.
Every bank gets the same interchange fee rate, regardless of how efficiently a bank conducts debit transactions.

git quick introduction

Git is distributed version control system, based on the concept of file system.

git init – Init of the new repository at the current directory.

git add <files> – Adds the files to the index/staging area.

git checkout — <file> – Removes the file from the index/staging area

git commit – Commits the change to repository.

git diff – diff report of the files between current working file and staging file / committed file.

git log – report of all the changes to the repository.

git reset HEAD <file> – Remove the file from index.

git remote -v – Working with the remote repository. Lists all the remote repositories.

git remote add origin – Adds the remote repository as origin.

git push -u origin – Push the changes to the remote repository.

git branch <branch-name> Create an branch

git checkout <branch-name> Switch to the branch

git merge <branch-name> merge the branch with the master

 

SSL Certificate Container formats

Sourced from http://serverfault.com/questions/9708/what-is-a-pem-file-and-how-does-it-differ-from-other-openssl-generated-key-file

 

  • .csr This is a Certificate Signing Request. Some applications can generate these for submission to certificate-authorities. The actual format is PKCS10 which is defined in RFC 2986. It includes some/all of the key details of the requested certificate such as subject, organization, state, whatnot, as well as the public key of the certificate to get signed. These get signed by the CA and a certificate is returned. The returned certificate is the public certificate (which includes the public key but not the private key), which itself can be in a couple of formats.
  • .pem   Defined in RFC’s 1421 through 1424, this is a container format that may include just the public certificate (such as with Apache installs, and CA certificate files /etc/ssl/certs), or may include an entire certificate chain including public key, private key, and root certificates. Confusingly, it may also encode a CSR (e.g. as used here) as the PKCS10 format can be translated into PEM. The name is from Privacy Enhanced Mail (PEM), a failed method for secure email but the container format it used lives on, and is a base64 translation of the x509 ASN.1 keys.
  • .key This is a PEM formatted file containing just the private-key of a specific certificate and is merely a conventional name and not a standardized one. In Apache installs, this frequently resides in /etc/ssl/private. The rights on these files are very important, and some programs will refuse to load these certificates if they are set wrong.
  • .pkcs12 .pfx .p12 Originally defined by RSA in the Public-Key Cryptography Standards, the “12” variant was enhanced by Microsoft. This is a passworded container format that contains both public and private certificate pairs. Unlike .pem files, this container is fully encrypted. Openssl can turn this into a .pem file with both public and private keys: openssl pkcs12 -in file-to-convert.p12 -out converted-file.pem -nodes

 

 

8 Shortest Stories with beautiful meaning

(1) Those who had coins, enjoyed in the rain.
Those who had notes, were busy looking for shelter.

(2) Man and God both met somewhere,
Both exclaimed …
“My creator”

(3) He asked are you-“Hindu or Muslim”
Response came- I am hungry

(4) The fool didn’t know it was impossible. …
So he did it.

(5) “Wrong number”, Said a familiar voice.

(6) What if, God asks you after you die ….
“So how was heaven??”

(7) “They told me that to make her fall in love I had to make her laugh.
But every time she laughs, I am the one who falls in love.”

(8) We don’t make friends anymore, We Add them.