Permalink
Browse files

Restore apostrophes to reduce the size of the diff

  • Loading branch information...
1 parent 8bdd0ce commit 511627c0887ccb02514110524206445e6b413bd6 @jpmckinney jpmckinney committed Jun 25, 2013
View
@@ -76,20 +76,20 @@ REST with JSON has become the favorite of developers and API owners, because it
### When Things Go Wrong — Error Handling
-One of the most important issues to remember in API strategy is, developers need to handle what happens when an error occurs; otherwise, access to data fails and subsequently so does the application. For the purposes of the service framework, an error is defined as an unexpected behavior that occurred during the process of a request. Its important to note that what might be considered an "error" can often be an expected behavior.
+One of the most important issues to remember in API strategy is, developers need to handle what happens when an error occurs; otherwise, access to data fails and subsequently so does the application. For the purposes of the service framework, an error is defined as an unexpected behavior that occurred during the process of a request. It's important to note that what might be considered an "error" can often be an expected behavior.
For instance, a search operation returning no results (a blank object) and an HTTP status 200 OK code might be construed as an error, but in reality this is not outside the realm of expected normal operation.
So really when we say errors we mean bad things happen like a database server goes down or a required parameter wasn't passed to a URI. Ultimately it is the responsibility of your code to anticipate and appropriately handle errors.
### Developing an API Ecosystem
-An API starts with the desire to share data or resources that a company offers. Its built with technologies like REST, XML, and JSON, and supported through documentation, along with a handful of code samples to show how to use it.
+An API starts with the desire to share data or resources that a company offers. It's built with technologies like REST, XML, and JSON, and supported through documentation, along with a handful of code samples to show how to use it.
-An API and its supporting developer area are created. And then, whats next? How does a simple API area build community? How does it evolve into a thriving ecosystem like Facebooks or Foursquares?
+An API and its supporting developer area are created. And then, what's next? How does a simple API area build community? How does it evolve into a thriving ecosystem like Facebook's or Foursquare's?
It all starts with developers. Giving developers a self-service, resource-rich environment where they have the spotlight and a voice that will encourage them in turn to contribute to the API community.
-An API owner has to support its APIs community, be proactive about reaching out to its community and know what it needs.
+An API owner has to support its API's community, be proactive about reaching out to its community and know what it needs.
Resources for developers need to be abundant and well organized. Common resources like blogs, forum, and FAQs are necessary. Tutorials, case studies and "How To’s" can take things even further.
View
@@ -10,12 +10,12 @@ Making data open and accessible in a standard, machine-readable format by defaul
**Save time and money responding to Freedom of Information Act (FOIA) requests.** When data is open by default, the public can access the information it seeks directly, freeing your agency from the time and cost expenditures related to responding to FOIAs.
-**Avoid duplicative internal research.** Transparency into the total universe of data held by your agency helps prevent the possibility of wasting funds re-collecting data simply because a particular program or department is unaware of that data’s existence. Further, it may be possible to reduce the scope and cost of new collections based on the ability to re-use and/or pair with existing data. Maintaining a central data catalog for your agency makes it easier to understand what information is currently available, and reviewing this catalog prior to the start of any new data collection is a recommended best practice.
+**Avoid duplicative internal research.** Transparency into the total universe of data held by your agency helps prevent the possibility of wasting funds re-collecting data simply because a particular program or department is unaware of that data's existence. Further, it may be possible to reduce the scope and cost of new collections based on the ability to re-use and/or pair with existing data. Maintaining a central data catalog for your agency makes it easier to understand what information is currently available, and reviewing this catalog prior to the start of any new data collection is a recommended best practice.
-**Discover complementary datasets held by other agencies.** The benefits of transparency into your agencys own datasets are amplified when every agency maintains its own standardized data catalog. Programs may realize that some or all of the data they need are already held by one or more other agencies, or that more powerful conclusions can be drawn from combining existing agency-held datasets with additional data across other agencies.
+**Discover complementary datasets held by other agencies.** The benefits of transparency into your agency's own datasets are amplified when every agency maintains its own standardized data catalog. Programs may realize that some or all of the data they need are already held by one or more other agencies, or that more powerful conclusions can be drawn from combining existing agency-held datasets with additional data across other agencies.
-**Empower employees to make better-informed, data-driven decisions.** The new requirement to publish details about each dataset owned by your agency in a specific format will power a central search engine at [Data.gov](http://www.data.gov) that every single Federal employee (and member of the public) can use to easily locate data held, owned, and/or created by the Federal Government. Making it easier to find existing data is key to being able to then incorporate that data into your agency’s everyday decision-making processes.
+**Empower employees to make better-informed, data-driven decisions.** The new requirement to publish details about each dataset owned by your agency in a specific format will power a central search engine at [Data.gov](http://www.data.gov) that every single Federal employee (and member of the public) can use to easily locate data held, owned, and/or created by the Federal Government. Making it easier to find existing data is key to being able to then incorporate that data into your agency's everyday decision-making processes.
-**Positive attention from the public, media, and other agencies.** In recent years, [entire events](http://energy.gov/articles/energy-datapalooza-unleashing-power-open-data-advance-our-energy-future) [celebrating](http://www.ed.gov/blog/2013/01/education-datapalooza-unleashing-the-power-of-open-data-to-help-students-parents-and-teachers/) the release and use of open government data -- many hosted by the White House -- have taken place, with corresponding media coverage and international attention. The more data your agency makes available in easy-to-consume formats, the more opportunities for positive coverage of the availability and impact of those data and your agency’s efforts.
+**Positive attention from the public, media, and other agencies.** In recent years, [entire events](http://energy.gov/articles/energy-datapalooza-unleashing-power-open-data-advance-our-energy-future) [celebrating](http://www.ed.gov/blog/2013/01/education-datapalooza-unleashing-the-power-of-open-data-to-help-students-parents-and-teachers/) the release and use of open government data -- many hosted by the White House -- have taken place, with corresponding media coverage and international attention. The more data your agency makes available in easy-to-consume formats, the more opportunities for positive coverage of the availability and impact of those data and your agency's efforts.
-**Generate revenue and create new jobs in the private sector.** McKinsey estimates that open health data alone adds over $300 billion to the economy each year. Entrepreneurs and non-profits integrate existing open government datasets in ways ranging from iPhone apps that connect you with the nearest hospital in case of an emergency, with [information](http://www.healthdata.gov/question/what-types-applications-have-been-developed-using-healthdatagov-data) from Health and Human Services, to matching prospective college students with the most appropriate schools, based on [IPEDS](http://nces.ed.gov/ipeds/) data maintained by the Department of Education. Making more of your agency data publicly available in standards-compliant, machine-readable formats makes it easier for private sector companies and entrepreneurs to create new innovations fueled by your agency’s data.
+**Generate revenue and create new jobs in the private sector.** McKinsey estimates that open health data alone adds over $300 billion to the economy each year. Entrepreneurs and non-profits integrate existing open government datasets in ways ranging from iPhone apps that connect you with the nearest hospital in case of an emergency, with [information](http://www.healthdata.gov/question/what-types-applications-have-been-developed-using-healthdatagov-data) from Health and Human Services, to matching prospective college students with the most appropriate schools, based on [IPEDS](http://nces.ed.gov/ipeds/) data maintained by the Department of Education. Making more of your agency data publicly available in standards-compliant, machine-readable formats makes it easier for private sector companies and entrepreneurs to create new innovations fueled by your agency's data.
View
@@ -41,7 +41,7 @@ The JSON representation of the catalog should track directly to the RDFa version
### RDFa Lite
-[RDFa Lite](http://www.w3.org/TR/rdfa-lite/) is a subset of RDFa (Resource Description Framework in Attribute) that provides a common syntax for expressing metadata on websites in a way that computers can understand and begin to formulate knowledge about those data about your organization. RDFa Lite embeds itself in existing, standard HTML pages. For example, if previously a dataset was described as `<h2>Name of Dataset</h2>`, RDFa would extend that markup as `<h2 property="dct:title">Name of Dataset</h2>` (notice the additional of the property field). This additional metadata is not visible when the page is rendered, and does not affect the page layout or content. It simply provides an additional level of description for search engines, crawlers, and other programmatic consumers of your site’s content. It is acceptable for the RDFa Lite file to contain only the machine-readable metadata, but agencies may wish to add human readable content to display the metadata to the public if they so desire.
+[RDFa Lite](http://www.w3.org/TR/rdfa-lite/) is a subset of RDFa (Resource Description Framework in Attribute) that provides a common syntax for expressing metadata on websites in a way that computers can understand and begin to formulate knowledge about those data about your organization. RDFa Lite embeds itself in existing, standard HTML pages. For example, if previously a dataset was described as `<h2>Name of Dataset</h2>`, RDFa would extend that markup as `<h2 property="dct:title">Name of Dataset</h2>` (notice the additional of the property field). This additional metadata is not visible when the page is rendered, and does not affect the page layout or content. It simply provides an additional level of description for search engines, crawlers, and other programmatic consumers of your site's content. It is acceptable for the RDFa Lite file to contain only the machine-readable metadata, but agencies may wish to add human readable content to display the metadata to the public if they so desire.
Generating Machine-Readable Reporting Files
View
@@ -7,4 +7,4 @@ filename: digital-pii-checklist.md
PII, also known as “personally identifiable Information,” is data potentially linked or linkable to individuals. The Digital PII Checklist identifies some common types of potential PII that may be collected, maintained, shared, or used in the mobile and digital environment. Agencies may use it as a baseline to ensure they have identified all data that may constitute PII prior to data release.
-For the checklist as well as additional information, see the CIO Councils [full report on Standardized Digital Privacy Controls](https://cio.gov/wp-content/uploads/downloads/2012/12/Standardized_Digital_Privacy_Controls.pdf).
+For the checklist as well as additional information, see the CIO Council's [full report on Standardized Digital Privacy Controls](https://cio.gov/wp-content/uploads/downloads/2012/12/Standardized_Digital_Privacy_Controls.pdf).
@@ -1,4 +1,4 @@
title,description,keyword,modified,publisher,person,mbox,identifier,accessLevel,dataDictionary,accessURL,webService,format,license,spatial,temporal,issued,accrualPeriodicity,language,granularity,dataQuality,theme,references,size,landingPage,feed,systemOfRecords
-Office Locations,A list of the agencys office locations and contact information.,keyword1,1/1/2013,Agency,"John, Smith",john.smith@agency.gov,1,Public,http://www.agency.gov/data/information/locations,http://www.agency.gov/data/raw/locations.zip,http://www.agency.gov/data/raw/locations.json,csv,public domain,United States,today,7/9/2012,6 months,English,Address,TRUE,Energy,http://www.agency.gov/data/information/locations/document.doc,44KB,http://www.agency.gov/offices,,
-Database Export,A full export of the agency’s database.,keyword2,2/1/2013,Agency,"Jane, Smith",jane.smith@agency.gov,2,Public,http://www.agency.gov/data/information/database,http://www.agency.gov/data/raw/database.csv,,xml,public domain,United States,2001-current,3/1/2012,yearly,English,Station,TRUE,Education,"http://www.agency.gov/bureau1/document3.doc, http://www.agency.gov/bureau1/document5.txt",5MB,http://www.agency.gov/data/information/database,http://www.agency.gov/data/raw/database.rss,http://www.agency.gov/systemsofrecord/system2
-System Data API,A restful web service for a system’s data set from 2012.,"keyword1, keyword2",12/15/2012,Agency,"Bill, Smith",bill.smith@agency.gov,3,Public,http://www.agency.gov/data/information/system_api,http://www.agency.gov/data/raw/system_2012.csv,http://www.agency.gov/data/raw/data_api.json,"csv, json",creative commons Cco,United States,2012,2/15/2013,weekly,English,Individual,TRUE,"Health, Education",http://www.agency.gov/bureau1/document3.pdf,300MB,http://www.agency.gov/developer/system,http://api.agency.gov/system.rss,http://www.agency.gov/systemsofrecord/system1
+Office Locations,A list of the agency's office locations and contact information.,keyword1,1/1/2013,Agency,"John, Smith",john.smith@agency.gov,1,Public,http://www.agency.gov/data/information/locations,http://www.agency.gov/data/raw/locations.zip,http://www.agency.gov/data/raw/locations.json,csv,public domain,United States,today,7/9/2012,6 months,English,Address,TRUE,Energy,http://www.agency.gov/data/information/locations/document.doc,44KB,http://www.agency.gov/offices,,
+Database Export,A full export of the agency's database.,keyword2,2/1/2013,Agency,"Jane, Smith",jane.smith@agency.gov,2,Public,http://www.agency.gov/data/information/database,http://www.agency.gov/data/raw/database.csv,,xml,public domain,United States,2001-current,3/1/2012,yearly,English,Station,TRUE,Education,"http://www.agency.gov/bureau1/document3.doc, http://www.agency.gov/bureau1/document5.txt",5MB,http://www.agency.gov/data/information/database,http://www.agency.gov/data/raw/database.rss,http://www.agency.gov/systemsofrecord/system2
+System Data API,A restful web service for a system's data set from 2012.,"keyword1, keyword2",12/15/2012,Agency,"Bill, Smith",bill.smith@agency.gov,3,Public,http://www.agency.gov/data/information/system_api,http://www.agency.gov/data/raw/system_2012.csv,http://www.agency.gov/data/raw/data_api.json,"csv, json",creative commons Cco,United States,2012,2/15/2013,weekly,English,Individual,TRUE,"Health, Education",http://www.agency.gov/bureau1/document3.pdf,300MB,http://www.agency.gov/developer/system,http://api.agency.gov/system.rss,http://www.agency.gov/systemsofrecord/system1
@@ -10,7 +10,7 @@
<li>
<strong>Description:</strong>
- <span rel="dct:description">A list of the agencys office locations and contact information.</span>
+ <span rel="dct:description">A list of the agency's office locations and contact information.</span>
</li>
<li>
@@ -151,7 +151,7 @@
<li>
<strong>Description:</strong>
- <span rel="dct:description">A full export of the agencys database.</span>
+ <span rel="dct:description">A full export of the agency's database.</span>
</li>
<li>
@@ -292,7 +292,7 @@
<li>
<strong>Description:</strong>
- <span rel="dct:description">A restful web service for a systems data set from 2012.</span>
+ <span rel="dct:description">A restful web service for a system's data set from 2012.</span>
</li>
<li>
@@ -3,7 +3,7 @@
<attribute rel="dct:title">Office Locations</attribute>
- <attribute rel="dct:description">A list of the agencys office locations and contact information.</attribute>
+ <attribute rel="dct:description">A list of the agency's office locations and contact information.</attribute>
<attribute rel="dcat:dataDictionary">http://www.agency.gov/data/information/locations</attribute>
@@ -60,7 +60,7 @@
<attribute rel="dct:title">Database Export</attribute>
- <attribute rel="dct:description">A full export of the agencys database.</attribute>
+ <attribute rel="dct:description">A full export of the agency's database.</attribute>
<attribute rel="dcat:dataDictionary">http://www.agency.gov/data/information/database</attribute>
@@ -117,7 +117,7 @@
<attribute rel="dct:title">System Data API</attribute>
- <attribute rel="dct:description">A restful web service for a systems data set from 2012.</attribute>
+ <attribute rel="dct:description">A restful web service for a system's data set from 2012.</attribute>
<attribute rel="dcat:dataDictionary">http://www.agency.gov/data/information/system_api</attribute>
Oops, something went wrong.

0 comments on commit 511627c

Please sign in to comment.