Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Pull request Compare This branch is 74 commits behind vaquarkhan:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ACID vs BASE
AWS
Case study
Design
ELKStack
ESB
Spring cloud
Togaf
Trunk base develoment
apache camel
bitcoin
cloud design
docker-java
integration design pattern
kafka
microservice
other
scala
springdata
2013octsvcodecampsecurerestapisoauth2-131002134922-phpapp01.pptx
2015_017_101_438662-API.pdf
20170426-oauth2openidmicroservices-170522091757.pptx
9781783987061_Sample.pdf
A-Scalable-Hierarchical-Clustering-Algorithm-Using-Spark--Spark-Summi…-iteblog.pdf
APACHE-TOREE--A-JUPYTER-KERNEL-FOR-SPARK-by-Marius-van-Niekerk-iteblog.pdf
API-55214-The_Maginot_Line_V2.pdf
API-Best-Practices-ebook-2016-12.pdf
API-best-practices-Slides-2016-11.pdf
ASPgems - Kappa Architecture (1).pdf
ASPgems - Kappa Architecture.pdf
AadhaarTechnologyArchitecture_March2014.pdf
Accelerating-Machine-Learning-and-Deep-Learning-At-Scale...With-Apach…-iteblog.pdf
Analysis-Andromeda-Galaxy-Data-Using-Spark--Spark-Summit-East-Talk-by…-iteblog.pdf
Apache Spark in 24 hrs .pdf
Apache-Carbondata--An-Indexed-Columnar-File-Format-for-Interactive-Qu…-iteblog.pdf
Apache-Spark-in-Cloud-and-Hybrid--Why-Security-and-Governance-Become-…-iteblog.pdf
ApacheConBigData - Introducing Apache Geode - final.pdf
ApacheSpark2014.pdf
Apache_Spark_Analytics_Made_Simple.pdf
Apache_Spark_Interview_Questions_Book (1).pdf
Artificial-Intelligence--How-Enterprises-Can-Crush-It-With-Apache-Spa…-iteblog.pdf
AvoidingMicroserviceMegadisasters .pptx
BDE-LeadingaHealthcareCaseStudy-QURAISHI.pdf
Big Data Analytics with Spark.pdf
Big-Data-Meets-Learning-Science--Keynote-by-Al-Essa-iteblog.pdf
BigDL--A-Distributed-Deep-Learning-Library-on-Spark--Spark-Summit-Eas…-iteblog.pdf
Bringing-HPC-Algorithms-to-Big-Data-Platforms--Spark-Summit-East-talk…-iteblog.pdf
Building-Realtime-Data-Pipelines-with-Kafka-Connect-and-Spark-Streami…-iteblog.pdf
Building-a-Dataset-Search-Engine-with-Spark-and-Elasticsearch--Spark-…-iteblog.pdf
Building-a-Real-Time-Fraud-Prevention-Engine-Using-Open-Source-(Big-D…-iteblog.pdf
Building_Microservices_Nginx.pdf
Building_Real-Time_Data_Platforms_MemSQL.pdf
Bulletproof-Jobs--Patterns-for-Large-Scale-Spark-Processing--Spark-Su…-iteblog.pdf
CON2306_Ashmore-Writing Microservices in Java-JavaOne-2015-10-28.pdf
Capture.PNG
Cheetsheet.pdf
Cloudera_Spark_Training-interbit.pdf
Cost-Based-Optimizer-Framework-for-Spark-SQL--Spark-Summit-East-talk-…-iteblog.pdf
Custom-Applications-with-Spark's-RDD--Spark-Summit-East-talk-by-Tejas…-iteblog.pdf
DDDTheGoodParts.pptx
Data-Science-Transformation-Via-Apache-Spark-on-Hybrid-Cloud--Keynote…-iteblog.pdf
DataProcessinArchitecture.pdf
Debugging-PySpark--Spark-Summit-East-talk-by-Holden-Karau-iteblog.pdf
Drizzle—Low-Latency-Execution-for-Apache-Spark--Spark-Summit-East-tal…-iteblog.pdf
ESG_Buyers_Guide_Databricks_September_2016_1.pdf
Ernest--Efficient-Performance-Prediction-for-Advanced-Analytics-on-Ap…-iteblog.pdf
Exceptions-are-the-Norm--Dealing-with-Bad-Actors-in-ETL-iteblog.pdf
Exploring-Spark-for-Scalable-Metagenomics-Analysis--Spark-Summit-East…-iteblog.pdf
Feature-Hashing-for-Scalable-Machine-Learning--Spark-Summit-East-talk…-iteblog.pdf
Fighting-Cybercrime--A-Joint-Task-Force-of-Real-Time-Data-and-Human-A…-iteblog.pdf
GemFire_ApacheCon.pdf
Git Demystified.pptx
Global-Empire-Building-for-Fun-and-Profit--Spark-Summit-East-talk-by-…-iteblog.pdf
Going-Real-Time--Creating-Frequently-Updating-Datasets-for-Personaliz…-iteblog.pdf
Hadoop Architecture.pdf
Hail--SCALING-GENETIC-DATA-ANALYSIS-WITH-APACHE-SPARK--Keynote-by-Cot…-iteblog.pdf
Horizontally-Scalable-Relational-Databases-with-Spark--Spark-Summit-E…-iteblog.pdf
How-to-Integrate-Spark-MLlib-and-Apache-Solr-to-Build-Real-Time-Entit…-iteblog.pdf
Insights-Without-Tradeoffs-Using-Structured-Streaming-keynote-by-Mich…-iteblog.pdf
JagsRamnarayan_and_JimBedenbaugh_BankingCaseStudyScalingWithLowLatencyUsingNewSQL.pdf
KafkaProducer-master.zip
Keeping-Spark-on-Track--Productionizing-Spark-for-ETL-iteblog.pdf
Lessons-Learned-from-Dockerizing-Spark-Workloads--Spark-Summit-East-t…-iteblog.pdf
Lessons_from_Large-Scale_Machine_Learning_Deployments_on_Spark.pdf
Machine Learning with Spark (1).pdf
Making-Structured-Streaming-Ready-for-Production-iteblog.pdf
MapReduceJobs-master.zip
Mastering-Advanced-Analytics-With-Apache-Spark.pdf
Meer klanten met OAuth.pptx
Microservice-OAuth2-Viquarkhan.pptx
Microservices-done-right-eBook-2016-11.pdf
Microservicesecurity-.pdf
Migrating-from-Redshift-to-Spark-at-Stitch-Fix--Spark-Summit-East-tal…-iteblog.pdf
ModelDB--A-System-to-Manage-Machine-Learning-Models--Spark-Summit-Eas…-iteblog.pdf
Monitoring-the-Dynamic-Resource-Usage-of-Scala-and-Python-Spark-Jobs-…-iteblog.pdf
Netflix's-Recommendation-ML-Pipeline-Using-Apache-Spark--Spark-Summit…-iteblog.pdf
New-Directions-in-pySpark-for-Time-Series-Analysis--Spark-Summit-East…-iteblog.pdf
Opaque--A-Data-Analytics-Platform-with-Strong-Security--Spark-Summit-…-iteblog.pdf
Optimizing Shuffle Performance in Spark.pdf
Optimizing-Apache-Spark-SQL-Joins-iteblog.pdf
Parallelizing-Existing-R-Packages-with-SparkR-iteblog.pdf
Problem-Solving-Recipes-Learned-from-Supporting-Spark--Spark-Summit-E…-iteblog.pdf
Processing-Terabyte-Scale-Genomics-Datasets-with-ADAM--Spark-Summit-E…-iteblog.pdf
RDDs-DataFrames-and-Datasets-in-Apache-Spark.pdf
README.md
RISELab--Enabling-Intelligent-Real-Time-Decisions-keynote-by-Ion-Stoi…-iteblog.pdf
Realtime-Analytical-Query-Processing-and-Predictive-Model-Building-on…-iteblog.pdf
Robust-and-Scalable-ETL-over-Cloud-Storage-with-Apache-Spark-iteblog.pdf
SPARK-CTGs.pdf
SSE15-22-Joseph-Bradley.pdf
Secured-(Kerberos-based)-Spark-Notebook-for-Data-Science--Spark-Summi…-iteblog.pdf
Semantic-Natural-Language-Understanding-with-Machine-Learned-Annotato…-iteblog.pdf
Spark Summit 2014 - Spark Streaming.pdf
Spark-Cookbook-eBook.pdf
Spark-TheNextTopComputeModel.pdf
Spark-and-Object-Stores-—What-You-Need-to-Know--Spark-Summit-East-tal…-iteblog.pdf
Spark-as-the-Gateway-Drug-to-Typed-Functional-Programming--Spark-Summ…-iteblog.pdf
Spark-for-Behavioral-Analytics-Research--Spark-Summit-East-talk-by-Jo…-iteblog.pdf
SparkSQL--A-Compiler-from-Queries-to-RDDs-iteblog.pdf
Spring Data - Modern Data Access for Enterprise Java .pdf
Spring-data-in- action.pdf
Teaching-Apache-Spark-Clusters-to-Manage-Their-Workers-Elastically--S…-iteblog.pdf
Time-Series-Analytics-with-Spark--Spark-Summit-East-talk-by-Simon-Oue…-iteblog.pdf
Time-evolving-Graph-Processing-on-Commodity-Clusters--Spark-Summit-Ea…-iteblog.pdf
Top Answers to Spark Interview Questions.docx
Trends-for-Big-Data-and-Apache-Spark-in-2017-by-Matei-Zaharia-iteblog.pdf
Tuning-and-Monitoring-Deep-Learning-on-Apache-Spark-iteblog.pdf
Using-Apache-Spark-for-Intelligent-Services--Keynote-at-Spark-Summit-…-iteblog.pdf
Web-design-the-missing-link-ebook-2016-11.pdf
What-No-One-Tells-You-About-Writing-a-Streaming-App--Spark-Summit-Eas…-iteblog.pdf
Zaharia M., et al. Learning Spark (O'Reilly, 2015)(274s).pdf
_config.yml
_f769dac2dfe1f9171ebc85265ac03093_Learning-representations-by-back-propagating-errors (1).pdf
advanced-spark-training.pdf
analyzingtimeseriesdatawithapachesparkandcassandra-150701140404-lva1-_time-series-app6891.pdf
cloud-native-java-designing-resilient-systems-with-spring-boot-spring-cloud-and-cloud-foundry.pdf
cloudera-spark.pdf
data-lake-solution-on-aws.pdf
databricks-spark-knowledge-base-150602121807-lva1-app6891.pdf
databricks-spark-reference-applications.pdf
datasci.pdf
deep-dive-with-spark-streamingtathagata-dasspark-meetup2013-06-17-130623151510-phpapp02.pptx
dgadiraju-code-master.zip
ebaymicroservicesv1-161111210539.pptx
flink.pdf
hawq-sigmod-2014.pdf
hdp2-Harthonwork-HDP2.3.pdf
high-performance-spark.pdf
how_to_run_spark_app.pdf
itas_workshop.pdf
lambda-architecure-on-for-batch-aws.pdf
large-scale-spark-talk-150219232451-conversion-gate01.pdf
matei-zaharia-part-2-amp-camp-2012-standalone-programs.pdf
mateizahariasics-cloud-day-2.pdf
microservice-thisis.pdf
microservices-sto.pdf
mlwithspark.pdf
oauth-jwt-161104115713.pdf
oauth2-0-120821214923-phpapp02 (1).ppt
oauth2-0-simplified-130405092138-phpapp02.pptx
overview.pdf
redp5336.pdf
role_of_biometric_technology_in_aadhaar_jan21_2012.pdf
s2gx2015microservicesecurity-150924203350-lva1-app6891.pdf
samlvsoauth-131214194530-phpapp01.pptx
shukla12parallelizing.pdf
sigmod_spark_sql.pdf
spark-certification-study-guide.pdf
spark-news-master.zip
spark-notes.pdf
sparksqlmeetup-141113023921-conversion-gate01.pptx
spring-data-gemfire-reference.pdf
syer-microservice-security-141104184302-conversion-gate01.pdf
tathgatdas.pdf
vfabric-gemfire-ug-7.0.1.pdf
visualapi.pdf
xiangrui (1).pdf

README.md

API Standards

Guidelines

This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).

This document borrows heavily from:

Pragmatic REST

These guidelines aim to support a truly RESTful API. Here are a few exceptions:

RESTful URLs

General guidelines for RESTful URLs

  • A URL identifies a resource.
  • URLs should include nouns, not verbs.
  • Use plural nouns only for consistency (no singular nouns).
  • Use HTTP verbs (GET, POST, PUT, DELETE) to operate on the collections and elements.
  • You shouldn’t need to go deeper than resource/identifier/resource.
  • Put the version number at the base of your URL, for example http://example.com/v1/path/to/resource.
  • URL v. header:
    • If it changes the logic you write to handle the response, put it in the URL.
    • If it doesn’t change the logic for each response, like OAuth info, put it in the header.
  • Specify optional fields in a comma separated list.
  • Formats should be in the form of api/v2/resource/{id}.json

Good URL examples

Bad URL examples

HTTP Verbs

HTTP verbs, or methods, should be used in compliance with their definitions under the HTTP/1.1 standard. The action taken on the representation will be contextual to the media type being worked on and its current state. Here's an example of how HTTP verbs map to create, read, update, delete operations in a particular context:

HTTP METHOD POST GET PUT DELETE
CRUD OP CREATE READ UPDATE DELETE
/dogs Create new dogs List dogs Bulk update Delete all dogs
/dogs/1234 Error Show Bo If exists, update Bo; If not, error Delete Bo

(Example from Web API Design, by Brian Mulloy, Apigee.)

Responses

  • No values in keys
  • No internal-specific names (e.g. "node" and "taxonomy term")
  • Metadata should only contain direct properties of the response set, not properties of the members of the response set

Good examples

No values in keys:

"tags": [
  {"id": "125", "name": "Environment"},
  {"id": "834", "name": "Water Quality"}
],

Bad examples

Values in keys:

"tags": [
  {"125": "Environment"},
  {"834": "Water Quality"}
],

Error handling

Error responses should include a common HTTP status code, message for the developer, message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined ID), links where developers can find more info. For example:

{
  "status" : 400,
  "developerMessage" : "Verbose, plain language description of the problem. Provide developers
   suggestions about how to solve their problems here",
  "userMessage" : "This is a message that can be passed along to end-users, if needed.",
  "errorCode" : "444444",
  "moreInfo" : "http://www.example.gov/developer/path/to/help/for/444444,
   http://drupal.org/node/444444",
}

Use three simple, common response codes indicating (1) success, (2) failure due to client-side problem, (3) failure due to server-side problem:

  • 200 - OK
  • 400 - Bad Request
  • 500 - Internal Server Error

Versions

  • Never release an API without a version number.
  • Versions should be integers, not decimal numbers, prefixed with ‘v’. For example:
    • Good: v1, v2, v3
    • Bad: v-1.1, v1.2, 1.3
  • Maintain APIs at least one version back.

Record limits

  • If no limit is specified, return results with a default limit.
  • To get records 51 through 75 do this:

Information about record limits and total available count should also be included in the response. Example:

{
    "metadata": {
        "resultset": {
            "count": 227,
            "offset": 25,
            "limit": 25
        }
    },
    "results": []
}

Request & Response Examples

API Resources

GET /magazines

Example: http://example.gov/api/v1/magazines.json

Response body:

{
    "metadata": {
        "resultset": {
            "count": 123,
            "offset": 0,
            "limit": 10
        }
    },
    "results": [
        {
            "id": "1234",
            "type": "magazine",
            "title": "Public Water Systems",
            "tags": [
                {"id": "125", "name": "Environment"},
                {"id": "834", "name": "Water Quality"}
            ],
            "created": "1231621302"
        },
        {
            "id": 2351,
            "type": "magazine",
            "title": "Public Schools",
            "tags": [
                {"id": "125", "name": "Elementary"},
                {"id": "834", "name": "Charter Schools"}
            ],
            "created": "126251302"
        }
        {
            "id": 2351,
            "type": "magazine",
            "title": "Public Schools",
            "tags": [
                {"id": "125", "name": "Pre-school"},
            ],
            "created": "126251302"
        }
    ]
}

GET /magazines/[id]

Example: http://example.gov/api/v1/magazines/[id].json

Response body:

{
    "id": "1234",
    "type": "magazine",
    "title": "Public Water Systems",
    "tags": [
        {"id": "125", "name": "Environment"},
        {"id": "834", "name": "Water Quality"}
    ],
    "created": "1231621302"
}

POST /magazines/[id]/articles

Example: Create – POST http://example.gov/api/v1/magazines/[id]/articles

Request body:

[
    {
        "title": "Raising Revenue",
        "author_first_name": "Jane",
        "author_last_name": "Smith",
        "author_email": "jane.smith@example.gov",
        "year": "2012",
        "month": "August",
        "day": "18",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam eget ante ut augue scelerisque ornare. Aliquam tempus rhoncus quam vel luctus. Sed scelerisque fermentum fringilla. Suspendisse tincidunt nisl a metus feugiat vitae vestibulum enim vulputate. Quisque vehicula dictum elit, vitae cursus libero auctor sed. Vestibulum fermentum elementum nunc. Proin aliquam erat in turpis vehicula sit amet tristique lorem blandit. Nam augue est, bibendum et ultrices non, interdum in est. Quisque gravida orci lobortis... "
    }
]

Mock Responses

It is suggested that each resource accept a 'mock' parameter on the testing server. Passing this parameter should return a mock data response (bypassing the backend).

Implementing this feature early in development ensures that the API will exhibit consistent behavior, supporting a test driven development methodology.

Note: If the mock parameter is included in a request to the production environment, an error should be raised.

JSONP

JSONP is easiest explained with an example. Here's one from StackOverflow:

Say you're on domain abc.com, and you want to make a request to domain xyz.com. To do so, you need to cross domain boundaries, a no-no in most of browserland.

The one item that bypasses this limitation is <script> tags. When you use a script tag, the domain limitation is ignored, but under normal circumstances, you can't really DO anything with the results, the script just gets evaluated.

Enter JSONP. When you make your request to a server that is JSONP enabled, you pass a special parameter that tells the server a little bit about your page. That way, the server is able to nicely wrap up its response in a way that your page can handle.

For example, say the server expects a parameter called "callback" to enable its JSONP capabilities. Then your request would look like:

    http://www.xyz.com/sample.aspx?callback=mycallback

Without JSONP, this might return some basic javascript object, like so:

    { foo: 'bar' }

However, with JSONP, when the server receives the "callback" parameter, it wraps up the result a little differently, returning something like this:

    mycallback({ foo: 'bar' });

As you can see, it will now invoke the method you specified. So, in your page, you define the callback function:

    mycallback = function(data){
        alert(data.foo);
    };

http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about?answertab=votes#tab-top


API Design

  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.

  1. 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.
  2. Use nouns as resource names (e.g. don’t use verbs in URLs).

  3. 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.
  4. Support filtering, sorting, and pagination on collections.

  5. 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.

  6. Support field projections on resources. Allow clients to reduce the number of fields that come back in the response.

  7. 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.
  8. 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.
  9. Use ISO 8601 timepoint formats for dates in representations.

  10. Consider connectedness by utilizing a linking strategy. Some popular examples are:

  11. 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.
  12. 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 /ratings

    How 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.

  13. 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/...).
  14. 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)
  15. Ensure that your GET, PUT, and DELETE operations are all idempotent. There should be no adverse side affects from operations.


mation that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. Roy Fielding’s dissertation

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1

resource can be a singleton or a collection resource may contain sub-collection resources

http://www.restapitutorial.com/lessons/restfulresourcenaming.html

Resources are within your system, name them as nouns as opposed to verbs or actions. RESTful URI should refer to a resource that is a thing instead of referring to an action. RESTful APIs are written for consumers. The name and structure of URIs should convey meaning to those consumers.

URL is not self- descriptive as the URI hierarchy is the same for all requests.

There are good arguments on both sides, but the commonly-accepted practice is to always use plurals in node names to keep your API URIs consistent across all HTTP methods. The reasoning is based on the concept that customers are a collection within the service suite and the ID (e.g. 33245) refers to one of those customers in the collection.

You ask if there is a case where pluralization doesn't make sense. Well, yes, in fact there is. When there isn't a collection concept in play. In other words, it's acceptable to use a singularized resource name when there can only be one of the resource—it's a singleton resource. For example, if there was a single, overarching configuration resource, you might use a singularized noun to represent that:

A resource may “contain” sub-collection resources also. For example, sub-collection resource “accounts” of a particular “customer” can be identified using the URN “/customers/{customerId}/accounts” (in a banking domain). Similarly, a singleton resource “account” inside the sub-collection resource “accounts” can be identified as follows: “customers/{customerId}/accounts/{accountId}”.

https://blog.philipphauer.de/restful-api-design-best-practices/

GET|PUT|DELETE http://www.example.com/configuration

Twitter: https://dev.twitter.com/docs/api Facebook: http://developers.facebook.com/docs/reference/api/ LinkedIn: https://developer.linkedin.com/apis

https://developers.google.com/+/web/api/rest/latest/activities/list

http://restfulapi.net/resource-naming/

https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling


You can’t perform that action at this time.